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Introduction 


This tutorial is designed to help people get up to speed quickly with building mainstream desktop 
graphical user interfaces with Tk, and in particular Tk 8.5, which is an incredibly significant 
milestone release and a significant departure from the older versions of Tk which most people know 
and teve recognize. 


The downside is that unless you know one or two particular things, it's actually not that significant a 
release; For backwards compatibility reasons, unless existing programs make a few simple changes, 
they won't look all that much different. So while this tutorial will certainly benefit newcomers to 
Tk, it will also help existing Tk developers bring their knowledge right up to date. It's a cliche, but I 
can't believe how much I've learned in writing this tutorial, and I've been using Tk for over fifteen 
years. 


The general state of Tk documentation (outside the Tcl-oriented reference documentation, which is 
excellent) is unfortunately not at a high point these days. This is particularly true for developers 
using Tk from languages other than Tcl, and developers working on multiple platforms. 


So this tutorial will, as much as possible, target developers on the three main platforms (Windows, 
Mac, Linux), and also be language-neutral. Initially, the tutorial will cover Tcl, Ruby, Perl and 
Python. Over time, additional languages may be added. Even if your own language isn't included, 
the chances are you'll still benefit; since all the languages use the same underlying Tk library, there's 
obviously a lot of overlap. 


This is also not a reference guide, it's not going to cover everything, just the essentials you need in 
95% of applications. The rest you can find in reference documentation. 


Who this Tutorial is for 


This tutorial is designed for developers building tools and applications in Tk. It's also concerned 
with fairly mainstream graphical user interfaces, with buttons, lists, checkboxes, rich text editing, 
2D graphics and so on. So if you're either looking to hack on Tk's internal C code, or build the next 
great 3D immersive game interface, this is probably not the material for you. 


This tutorial also doesn't teach you the underlying programming language (Tcl, Ruby, Perl, Python, 
etc.), so you should have a basic grasp on that already. Similarly, you should have a basic 
familiarity with desktop applications in general, and while you don't have to be a user interface 
designer, some appreciation of GUI design is always helpful. 


Modern Best Practices 


This tutorial is all about building modern Tk user interfaces using the current tools Tk has to offer. 
It's all about the best practices you need to know to do this. 


For most tools, you wouldn't think you'd have to say something like that, but for Tk that's not the 
case. Tk has had a very long evolution (see Tk Backgrounder), and any evolution tends to leave you 
with a bit of cruft; couple that with how much graphical user interface platforms and standards have 
evolved in that time, and you can see where keeping something as large and complex as a GUI 
library up to date as well as backwards compatible may be challenging. 


Tk has, in recent years, gotten a bad rap, to put it mildly. Some of this has been well deserved, most 
of it not so much. Like any GUI tool, it can be used to create absolutely terrible looking and 
outdated user interfaces, but with the proper care and attention, it can also be used to create 
spectacularly good ones as well. Most people know about the crappy ones; most of the good ones 
people don't even know are done in Tk. In this tutorial, we're going to focus on what you need to 
build good user interfaces, which isn't nearly as hard as it used to be before Tk 8.5. 


So modern desktop graphical user interfaces, using modern conventions and design sense, using the 
modern tools provided by Tk 8.5. 


Tk Extensions 


When it comes to modern best practices, Tk extensions deserve a special word of note. Over the 
years, a number of groups have provided all kinds of add-ons to Tk, for example adding new 
widgets not available in the core (or at least not at the time). Some well-known and quite popular 
Tk extensions include BLT, Tix, Widgets, BWidgets; there are many, many others. 


Many of these extensions were created years ago. Because core Tk has always been highly 
backwards compatible, these extensions generally continue to work with newer versions. However, 
many have not been updated, or not been significantly updated, in a long time. They may not reflect 
current platform conventions or styles, and so while they "work", they can make your application 
appear extremely dated or out of place. 


If you do decide to use Tk extensions, it's highly recommended that you investigate and review your 
choices carefully. 


The Better Way Forward 


Tk also gives you a lot of choices. There are at least six different ways to layout widgets on the 
screen, often multiple different widgets that could accomplish the same thing, especially if you 
count the huge assortment of Tk extensions like Tix, BLT, BWidgets, Itk and others. Most of these 
also are older, most not updated and therefore crappy looking, and in many cases, the facilities they 
provide have been obsoleted by newer and more modern facilities recently built into Tk itself. But 
for backwards compatibility reasons, most of these old ways of doing things still keep working, 
year after year. That doesn't necessarily mean people should still be using some of them. 


So there are a lot of choices in Tk, but frankly, all that choice gets in the way. If you want to learn 
and use Tk, you don't need all the choices, you need the right choice, so you don't have to do all the 
research and make that choice yourself. That's what this tutorial will give you. Think of it as the 
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documentation equivalent of opinionated software. So we'll often use different ways of doing things 
than in other documentation or examples; often, it's because when those were written, the better 
ways didn't even exist yet. Later on, once you're an expert, and you're encountering some wacky 
situation where the normal choice doesn't fit, you can go hunt around for alternatives. 


How to Use 


While the tutorial is designed to be used linearly, feel free to jump around as you see fit. We'll often 
provide links where you can go for more information, whether links to other documentation on this 
site, such as our "widget roundup" providing usage info on each Tk widget, or to external 
documentation, such as the full reference for a particular command. 


The tutorial also lets you select what language (Tcl, Ruby, Perl or Python) to show. You can change 
this by the "Show:" popup menu which is located in the sidebar, near the top right of each page in 
the tutorial. But it also lets you see how Tk is used by all the different languages, which can itself be 
quite interesting and useful. 


Conventions 

Asis typically done, code listings, interpreter or shell commands and responses will be indicated 
witha fixed-width font. When showing an interactive session with the interpreter, the parts 
that you enter will additionally be in bo1d fixed-width. 


When describing procedure or method calls, the literal parts (e.g. the method name) will be in plain 
fixed-width font, parameters where you should fill in the actual value will add italics, and optional 
parameters will be surrounded by '?', e.g. "set variable ?value?". 


A number of icons appearing to the left of text are used, as follows: 
This paragraph consists of material that is specific to the Python binding to Tk. 


This paragraph will help point out common mistakes that people make, or suggest useful but not 
necessarily obvious solutions related to the topic. 


This indicates a new way of doing things in Tk 8.5 that is very different from the way things would 
have been done previously. People familiar with older versions of Tk, or working on programs 
developed with older versions of Tk, should pay close attention. 


This paragraph provides some additional background information, not strictly necessary to 
understanding the topic at hand, but that might help you understand a bit more about how or why 
things are done the way they are. 


This indicates some error in the tutorial itself which hasn't yet been corrected, or a section that has 
been deleted but not yet replaced. 


This indicates an area in Tk that could most charitably be described as a "rough edge". It may 
indicate a bad or missing API requiring you to use a workaround in your code. Because these things 


tend to get fixed up over time, it's worth marking them in your code with a "TODO" so you can 
remember to go back later and see if a newer API resolves the problem cleanly. 


Installing Tk 


In this chapter, you'll get Tk installed on your machine, verify it works, and then see a quick 
example of what a Tk program looks like. 


Though pretty much all Mac OS X and Linux machines come with Tk installed already, it's often an 
older version (typically 8.4.x). You want to make sure you've got at least version 8.5 (or possibly 
8.6) to use the new widget set, so if that's not already there, you'll want to install the newer version. 


Though there are lots of ways to install Tk, the easiest is to download and install one of the versions 
provided by ActiveState (www.activestate.com). 


ActiveState is a company that sells professional developer tools for dynamic languages. They also 
provide (for free) quality-controlled distributions of some of these languages, and happen to employ 
a number of core developers of these languages. 


Installing Tk on Mac OS X 


Tkinter (and, since Python 3.1, ttk) are included with all standard Python distributions on Mac OS 
X. However, more recent distributions do not always include the underlying Tcl and Tk libraries 
and support files, which must be installed separately. 


While there are several different ways to do get Tcl and Tk onto your machine, the easiest and most 
recommended is to use the ActiveTcl distribution. 


If you're a masochist and want to read about other Tcl/Tk options and variations and how they 
interact with Python, see the Mac Tcl/Tk page at python.org. 


Install ActiveTcl 


In your web browser, go to www.activestate.com, and follow along the links to download the 
Community Edition of ActiveTcl, available as a universal binary. Make sure you're downloading an 
8.5.x version, not an older 8.4.x version. 


Run the installer to get Tcl and Tk loaded onto your machine. 


Install Python 


It is important that you use a version of Python supporting Tk 8.5 or greater, and ttk. We 
recommend using the standard Python 3.x Mac installer that can be downloaded from python.org. 


Earlier versions of this tutorial recommended using ActiveState's ActivePython. Older versions used 
to include Tcl/Tk libraries and support files, but more recent versions no longer do, and require 
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downloading them separately, e.g. via ActiveTcl. Therefore the standard Python distribution works 
just as well, and the end result is the same. 


Run the installer and follow along. You'll end up with a fresh install of ActivePython in 
/Library/Frameworks, along with links to the versioned Python binaries placed in /usr/local/bin (e.g. 
'python3.4' if you downloaded ActivePython 3.4.x). From a Terminal window you should then be 
able to run a Python shell: 


% /usr/local/bin/python3.4 


This should give you the Python command prompt. From the prompt, enter these two commands: 


>>> import tkinter 
>>> tkinter._test() 


This should pop up a small window; the first line at the top of the window should say "This is 
Tcl/Tk version 8.5"; make sure it is not 8.4! 


You can also get the exact version of Tcl/Tk that is being used with: 


>>> tkinter.Tcl().eval('info patchlevel' ) 


which should return something like '8.5.18'. 


Verified install using ActiveTcl 8.5.18.0 and Python 3.4.3 from python.org on Mac OS X 10.10.3. 


Installing Tk on Windows 


Tkinter (and, since Python 3.1, ttk) are included with all standard Python distributions. It is 
important that you use a version of Python supporting Tk 8.5 or greater, and ttk. We recommend 
using the standard Python 3.x Windows installer which can be downloaded from python.org. 


Earlier versions of this tutorial recommended using the ActivePython distribution from ActiveState; 
that will work as well. Both contain Python as well as the underlying Tcl/Tk libraries. 


Run the installer, and follow along. You'll end up with a fresh install of ActivePython, located in, 
e.g. CApython34. From a Windows command prompt, or the Start Menu's "Run..." command, you 
should then be able to run a Python shell via: 


% C:\python34\python 


This should give you the Python command prompt. From the prompt, enter these two commands: 


>>> import tkinter 
>>> tkinter._test() 


This should pop up a small window, the first line at the top of the window should say "This is 
Tcl/Tk version 8.5" (or "8.6"); make sure it is not 8.4! 


You can also get the exact version of Tcl/Tk that is being used with: 
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>>> tkinter.Tcl().eval('info patchlevel') 


which should return something like '8.5.18'. 


Verified install using Python 3.4.3 from python.org (containing Tcl/Tk 8.6.1) on Windows 8.1. 


Installing Tk on Linux 


Tkinter (and, since Python 3.1, ttk) are included with all standard Python distributions. It is 
important that you use a version of Python supporting Tk 8.5 or greater, and ttk. Many Python 
distributions will not automatically install the underlying Tcl and Tk libraries however. 


You have several different options to get Python and Tkinter onto your machine. 


Option 1. Your Linux Distribution's Package Manager 
Currently supported Linux distributions will usually already include a recent version of Python 3.x 


(or have a .deb, .rpm, etc. package available to install). If so, this is usually the easiest way to go. 


However, after you're done, start up a Python shell (e.g. /usr/bin/python3.4) and verify the install 
(see below). You may find that when you try to 'import tkinter' that you get an error that you need to 
install another package. If so, follow the instructions, and try again. 


For example, running Ubuntu 14.04 LTS, Python 3.4.0 is already included. However, you also need 
to install a separate package, python3-tk, to use Tkinter, e.g. 


% sudo apt-get install python3-tk 


In this case, that package provides Tcl/Tk 8.6.1 libraries to be used with Python. 


Option 2. Install ActivePython 
The "ActivePython" distribution from ActiveState includes both Python and the necessary Tcl/Tk 


libraries. 


In your web browser, go to www.activestate.com, and follow along the links to download the 
Community Edition of ActivePython for Linux. Make sure you're downloading a 3.1 or newer 
version. 


Unpack it, run the installer (sudo ./install.sh), and follow along. You'll end up with a fresh install of 
ActivePython, located in e.g. /opt/ActivePython-3.4. From a Terminal window you should then be 
able to run a Python shell via: 


% /opt/ActivePython-3.4/bin/python3.4 


See below to verify your install. 
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Option 3. Install Tcl/Tk and Compile the Standard Python Distribution 
If you'd like to use the standard source distribution from python.org, you can certainly do that. 


But to do so, you'll need to get the Tcl and Tk include files and libraries loaded on your machine 
first. While there are again several ways to do that, the easiest is to download and install ActiveTcl. 


In your web browser, go to www.activestate.com, and follow along the links to download the 


Community Edition of ActiveTcl for Linux. Make sure you're downloading a 8.5 or newer version. 


Unpack it, run the installer (./install.sh), and follow along. You'll end up with a fresh install of 
ActiveTcl, located in e.g. /opt/ActiveTcl-8.5. 


Next, download the current Python 3.x source distribution from python.org, and unpack it. On your 
configure line, you'll need to tell it how to find the version of Tcl/Tk you installed. Then build as 
usual: 


% ./configure --with-tcltk-includes='-I/opt/ActiveTcl-8.5/include' 
--with-tcltk-libs='/opt/ActiveTcl-8.5/1lib/libtc18.5.so /opt/ActiveTcl- 

8.5/1ib/1libtk8.5.s0' 

% ./make 

% ./make install 


Make sure to verify your install (see below). 


Didn't work? There may have been an error compiling Python's tkinter code. To check, from the 
main Python source directory, try "touch Modules/_tkinter.c" (note the underscore) and then 
"make" to recompile it. Watch closely for error messages. 


The most common thing is that the way you specified the Tcl/Tk include and libraries needs to be 
changed somehow. Or if you get messages that certain include files can't be found (e.g. 
"X11/Xlib.h") you may need to install additional packages on your Linux distribution (e.g. "apt-get 
install libx11-dev"). Once you get it to compile without errors, don't forget to "make install". 


Verifying your Install 
At the Python command prompt, enter these two commands: 


>>> import tkinter 
>>> tkinter._test() 


This should pop up a small window; the first line at the top of the window should say "This is 
Tcl/Tk version 8.5"; make sure it is not 8.4! 


If it gives you an error when you try to ‘import tkinter' (e.g. "If this fails your Python may not be 
configured for Tk"), something hasn't been set up right. If you compiled Python yourself, see above 
to check for compile errors. 


You can also get the exact version of Tcl/Tk that is being used with: 


>>> tkinter.Tcl().eval('info patchlevel' ) 
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which should return something like '8.5.18'. 


Verified install using ActiveTcl 8.5.18, Python 3.4.3 from python.org on Ubuntu 14.04 LTS 


The Obligatory First Program 


To make sure that everything actually did work, let's try to run a "Hello World" program in Tk. 
While for something this short you could just type it in directly to the interpreter, instead use your 
favorite text editor to put it in a file. 


from tkinter import * 

from tkinter import ttk 

root = Tk() 

ttk.Button(root, text="Hello World").grid() 
root.mainloop() 


Save this to a file named 'hello.py'. From a command prompt, type: 


% python hello.py 


Couldn't find hello.py? You might be looking in the wrong directory. Try providing the full path to 
hello.py. 


E 


Hello World Hello World 


Mac OS X Windows 


Hello World | 


Linux 


Our First Program. Some work left to do before the IPO. 


A First (Real) Example 


With that out of the way, let's try a slightly more useful example, which will give you an initial feel 
for what the code behind a Tk program looks like. 


Design 


The example we'll use is a simple GUI tool that will convert a number of feet to the equivalent 
number of meters. If we were to sketch this out, it might look something like this: 
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A sketch of our feet to meters conversion program. 


So it looks like we have a short text entry widget that will let us type in the number of feet, and a 
'Calculate' button that will get the value out of that entry, perform the calculation, and then put the 
resulting number of meters on the screen just below where the entry is. We've also got three static 
labels ("feet", "is equivalent to", and "meters") which help our user figure out how to use the 
interface. 


In terms of layout, things seem to naturally divide into three columns and three rows: 


[zara 


The layout of our user interface, which follows a 3 x 3 grid. 


Code 


Now here is the Python code to create this program. 


from tkinter import * 
from tkinter import ttk 


def calculate(*args): 
try: 
value = float(feet.get()) 
meters.set((0.3048 * value * 10000.0 + 0.5)/10000.0) 
except ValueError: 
pass 


root = Tk() 
root.title("Feet to Meters") 
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mainframe = ttk.Frame(root, padding="3 3 12 12") 
mainframe.grid(column=0, row=0, sticky=(N, W, E, S)) 
mainframe.columnconfigure(0, weight=1) 
mainframe.rowconfigure(0, weight=1) 


feet = Stringvar() 
meters = StringVar() 


feet_entry = ttk.Entry(mainframe, width=7, textvariable=feet ) 
feet_entry.grid(column=2, row=1, sticky=(W, E)) 


ttk.Label(mainframe, textvariable=meters).grid(column=2, row=2, sticky=(W, E)) 
ttk.Button(mainframe, text="Calculate", command=calculate).grid(column=3, row=3, 
sticky=w) 

ttk.Label(mainframe, text="feet").grid(column=3, row=1, sticky=W) 
ttk.Label(mainframe, text="is equivalent to").grid(column=1, row=2, sticky=E) 
ttk.Label(mainframe, text="meters").grid(column=3, row=2, sticky=W) 

for child in mainframe.winfo_children(): child.grid_configure(padx=5, pady=5) 


feet_entry.focus() 
root.bind('<Return>', calculate) 


root.mainloop() 


And the resulting user interface: 


600 Feet to Meters 
fee 
is equivalent to 0.3048 meters 


Calculate 


Screenshot of our completed feet to meters user interface (on Mac OS X, Windows and Linux). 


A Note on Coding Style 


Each of the languages included in this tutorial has a variety of coding styles and conventions 
available to choose from, which help determine conventions for variable and function naming, 
procedural, functional or object-oriented styles, and so on. 


Because the focus on this tutorial is Tk, this tutorial will keep things as simple as possible, generally 
using a very direct coding style, rather than wrapping up most of our code in procedures, modules, 
objects, classes and so on. As much as possible, you'll also see the same names for objects, 
variables, etc. used across the languages for each example. 
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Step-by-Step Walkthrough 


Let's take a closer look at that code, piece by piece. For now, all we're trying to do is get a basic 
understanding of the types of things we need to do to create a user interface in Tk, and roughly what 
those things look like. We'll go into details later. 


from tkinter import * 
from tkinter import ttk 


These two lines tell Python that our program needs two modules. The first, "tkinter", is the 
standard binding to Tk, which when loaded also causes the existing Tk library on your system to be 
loaded. The second, "ttk", is Python's binding to the newer "themed widgets" that were added to 
Tk in 8.5. 


Notice that we've imported everything from the tkinter module, so that we can call tkinter functions 
etc. without prefixing them, which is standard Tkinter practice. However, because we've imported 
just "ttk" itself, that means we'll need to prefix anything inside that module. So for example 
calling "Entry(...)'" would invoke the function inside the tkinter module, while we'd need 
"ttk.Entry(...)" to invoke the function inside ttk. As you'll see, several functions are 
defined in both modules, and sometimes you will need both, depending on the context. Making the 
ttk calls explicit facilitates this, and will be the style used in this tutorial. 


One of the first things you'll find if you're migrating new code over, is that the name of the Tkinter 
module is now lowercase, i.e. "tkinter", rather than "Tkinter". This was changed as of Python 3.0. 
root = Tk() 

root.title("Feet to Meters") 

mainframe = ttk.Frame(root, padding="3 3 12 12") 

mainframe.grid(column=0, row=0, sticky=(N, W, E, S)) 
mainframe.columnconfigure(0, weight=1) 

mainframe.rowconfigure(0, weight=1) 


Yes, the "calculate" function appeared before this. We'll describe it down below, but need to 
include it near the start because we reference it in other parts of the program. 


Next, the above lines set up the main window, giving it the title "Feet to Meters". Next, we create a 
frame widget, which will hold all the content of our user interface, and place that in our main 
window. The "columnconfigure"/"rowconfigure" bits just tell Tk that if the main 
window is resized, the frame should expand to take up the extra space. 


Strictly speaking, we could just put the other parts of our interface directly into the main root 
window, without the intervening content frame. However, the main window isn't itself part of the 
"themed" widgets, so its background color wouldn't match the themed widgets we will put inside it. 
Using a "themed" frame widget to hold the content ensures that the background is correct. 

feet = StringVar() 

meters = StringVar() 

feet_entry = ttk.Entry(mainframe, width=7, textvariable=feet ) 


feet_entry.grid(column=2, row=1, sticky=(W, E)) 
ttk.Label(mainframe, textvariable=meters).grid(column=2, row=2, sticky=(W, E)) 
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ttk.Button(mainframe, text="Calculate", command=calculate).grid(column=3, row=3, 
sticky=w) 


The preceding lines create the three main widgets in our program: the entry where we type the 
number of feet in, a label where we put the resulting number of meters, and the calculate button that 
we press to perform the calculation. 


For each of the three widgets, we need to do two things: create the widget itself, and then place it 
onscreen. All three widgets, which are 'children' of our content window are created as instances of 
one of Tk's themed widget classes. At the same time as we create them, we give them certain 
options, such as how wide the entry is, the text to put inside the Button, etc. The entry and label 
each are assigned a mysterious "textvariable"; we'll see what that does shortly. 


If the widgets are just created, they won't automatically show up on screen, because Tk doesn't 
know how you want them to be placed relative to other widgets. That's what the "grid" part does. 
Remembering the layout grid for our application, we place each widget in the appropriate column 
(1, 2 or 3), and row (also 1, 2 or 3). The "sticky" option says how the widget would line up 
within the grid cell, using compass directions. So "w" (west) means anchor the widget to the left 
side of the cell, "we" (west-east) means anchor it to both the left and right sides, and so on. 
ttk.Label(mainframe, text="feet").grid(column=3, row=1, sticky=W) 


ttk.Label(mainframe, text="is equivalent to").grid(column=1, row=2, sticky=E) 
ttk.Label(mainframe, text="meters").grid(column=3, row=2, sticky=W) 


The above three lines do exactly the same thing for the three static text labels in our user interface; 
create each one, and place it onscreen in the appropriate cell in the grid. 
for child in mainframe.winfo_children(): child.grid_configure(padx=5, pady=5) 


feet_entry.focus() 
root.bind('<Return>', calculate) 


The preceeding three lines help put some nice finishing touches on our user interface. 


The first line walks through all of the widgets that are children of our content frame, and adds a 
little bit of padding around each, so they aren't so scrunched together. We could have added these 
options to each "grid" call when we first put the widgets onscreen, but this is a nice shortcut. 


The second line tells Tk to put the focus on our entry widget. That way the cursor will start in that 
field, so the user doesn't have to click in it before starting to type. 


The third line tells Tk that if the user presses the Return key (Enter on Windows) anywhere within 
the root window, that it should call our calculate routine, the same as if the user pressed the 
Calculate button. 


def calculate(*args): 
try: 
value = float(feet.get()) 
meters.set((0.3048 * value * 10000.0 + 0.5)/10000.0) 
except ValueError: 
pass 
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Here we define our calculate procedure, which is called either when the user presses the Calculate 
button, or hits the Return key. It performs the feet to meters calculation, taking the number of feet 
from our entry widget, and placing the result in our label widget. 


Say what? It doesn't look like we're doing anything with those widgets! Here's where the magic 
"textvariable" options we specified when creating the widgets come into play. We specified 
the global variable "feet" as the textvariable for the entry, which means that anytime the entry 
changes, Tk will automatically update the global variable feet. Similarly, if we explicitly change the 
value of a textvariable associated with a widget (as we're doing for "meters" which is attached to 
our label), the widget will automatically be updated with the current contents of the variable. Slick. 


root.mainloop() 


This final line tells Tk to enter its event loop, which is needed to make everything run. 


What's Missing 


It's also worth examing what we didn't have to include in our Tk program to make it work. For 
example: 


e we didn't have to worry about redrawing the screen as things changed 

e we didn't have to worry about parsing and dispatching events, hit detection, or handling 
events on each widget 

e we didn't have to provide a lot of options when we created widgets; the defaults seemed to 
take care of most things, and so we only had to change things like the text the button 
displayed 

e we didn't have to write complex code to get and set the values of simple widgets; we just 
attached them to variables 

e we didn't have to worry about what happens when the user closes the window or resizes it 

e we didn't need to write extra code to get this all to work cross-platform 


Tk Concepts 


With a first example behind you, you should have a basic idea of what a Tk program might look like 
and the types of tasks it needs to accomplish. We'll step back and look at three broad concepts that 
you need to know to understand Tk: widgets, geometry management, and event handling. 


Widgets 
Widgets are all the things that you see onscreen. In our example, we had a button, an entry, a few 
labels, and a frame. Others are things like checkboxes, tree views, scrollbars, text areas, and so on. 
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Widgets are what are often referred to as "controls"; you'll also often see them referred to as 
"windows", particularly in Tk's documentation, a holdover from its X11 roots (so under that 
terminology, both a toplevel window and things like a button would be called windows). 


Here is an example showing some of Tk's widgets, which we'll cover individually shortly. 


Done | 


Special Y| Special 
_) Radio E pac © Radio [Y] Specia 


- ¡Sun v 


112345 


Mac OS X Windows 
Several Tk Widgets. 


Widget Classes 


Widgets are objects, instances of classes that represent buttons, frames, and so on. So the first thing 
you'll need to do is identify the specific class of the widget you'd like to instantiate. This tutorial and 
the widget roundup will help with that. 


Window Hierarchy 


The other thing you'll need to know is the parent of the widget instance you'd like to create. In Tk, 
all widgets are part of a window hierarchy, with a single root at the top of the hierarchy. This 
hierarchy can be arbitrarily deep; so you might have a button in a frame in another frame within the 
root window. Even a new toplevel window is part of that same hierarchy, with it and all its contents 
forming a subtree of the overall window hierarchy. 


In our metric conversion example, we had a single frame that was created as a child of the root 
window, and that frame had all the other controls as children. The root window was a container for 
the frame, and was therefore the frame's parent. The complete hierarchy for the example looked like 
this: 


root 


content frame 


feet meters (result) calculate Ma . equiv alent to' 


entry label button label label label 
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The window hierarchy of the metric conversion example. 


Creating and Using Widgets 


Each separate widget is a Python object. When creating a widget, you must pass its parent as a 
parameter to the widget creation function. The only exception is the "root" window, which is the 
toplevel window that will contain everything else. That is automatically created, and it does not 
have a parent. For example: 


root = Tk() 
content = ttk.Frame(root) 
button = ttk.Button(content) 


Whether or not you save the widget object in a variable is entirely up to you, and depends of course 
whether you'll need to refer to it later. Because the object is inserted into the widget hierarchy, it 
won't be garbage collected even if you don't keep your own reference to it. 


If you snuck a peak at how Tcl manages widgets, you'll see each widget has a specific pathname; 
you'll also see this pathname referred to in Tk reference documentation. Tkinter chooses and 
manages all these pathnames for you behind the scenes, so you should never have to worry about 
them. If you do though, you can get the pathname from a widget by calling "Str (widget)". 


Configuration Options 


All widgets also have a number of different configuration options, which generally control how 
they are displayed or how they behave. 


The options that are available depend upon the widget class of course. There is a lot of consistency 
between different widget classes, so options that do pretty much the same thing tend to be named 
the same. So both a button and a label have a "text" option to adjust the text the widget displays, 
while a scrollbar for example would not have a "text" option since it's not needed. In the same 
way, the button has a "command" option telling it what to do when pushed, while a label, which 
holds just static text, does not. 


Configuration options can be set when the widget is first created, by passing along the names and 
values of the options as optional parameters. You can later check what the value of those options 
are, and with a very small number of exceptions, change them at any time. If you're not sure what 
all the different options are for a widget, you can ask the widget to provide it. This gives you a long 
list of all the options, and for each option, you can see the name of the option and its current value 
(along with three other attributes which you won't normally need to worry about). 


This is all best illustrated with the following interactive dialog with the interpreter. 


% python 

>>> from tkinter import * 

>>> from tkinter import ttk 

>>> root = Tk() 

create a button, passing two options: 

>>> button = ttk.Button(root, text="Hello", command="buttonpressed" ) 
>>> button.grid() 
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check the current value of the text option: 

>>> button['text'] 

'Hello' 

change the value of the text option: 

>>> button['text'] = 'goodbye' 

another way to do the same thing: 

>>> button.configure(text='goodbye' ) 

check the current value of the text option: 

>>> button['text'] 

'goodbye' 

get all information about the text option: 

>>> button.configure('text') 

('text', 'text', 'Text', '', 'goodbye') 

get information on all options for this widget: 

>>> button.configure() 

{'cursor': ('cursor', 'cursor', 'Cursor', '', ''), 'style': ('style', 'style', 
'Style', A ADF 

'default': ('default', 'default', 'Default', <index object at Ox00DFFD10>, 
<index object at 0Ox00DFFD10>), 


'text': ('text', 'text', 'Text', '', 'goodbye'), 'image': ('image', 'image', 
'Image', SS ry, 

‘class': ('class', '', '', '', ''), 'padding': ('padding', 'padding', 'Pad', '', 
width": ('width', 'width', 'Width', '', ''), 


'state': ('state', 'state', 'State', <index object at 0x0167FA20>, <index object 
at 0x0167FA20>), 


'command': ('command', 'command' , 'Command', '', 'buttonpressed'), 
'textvariable': ('textvariable', 'textVariable', 'Variable', '', ''), 
'compound': ('compound', 'compound', 'Compound', <index object at 0x0167FA08>, 
<index object at 0x0167FA08>), 

'underline': ('underline', 'underline', 'Underline', -1, -1), 

'takefocus': ('takefocus', 'takeFocus', 'TakeFocus', '', 'ttk::takefocus' )} 


Geometry Management 


If you've been playing around creating widgets, you've probably noticed that just by creating them 
they didn't end up showing up onscreen. Having things actually put in the onscreen window, and 
precisely where in the window they show up is a separate step called geometry management. 


In our example, this positioning was accomplished by the "grid" command, where we passed 
along the column and row we wanted each widget to go in, how things were to be aligned within the 
grid, and so on. Grid is an example of a geometry manager (of which there are several in Tk, grid 
being the most useful). We'll talk about grid in detail in a later chapter, but for now we'll look at 
geometry management in general. 


A geometry manager's job is to figure out exactly where those widgets are going to be put. This 
turns out to be a very difficult optimization problem, and a good geometry manager relies on quite 
complex algorithms. A good geometry manager provides the flexibility, power and ease of use that 
makes programmers happy, and Tk's "grid" is without a doubt one of the absolute best. A poor 
geometry manager... well, all the Java programmers who have suffered through "GridBagLayout" 
please raise their hands. 


22 


The Problem 


The problem for a geometry manager is to take all the different widgets the program creates, plus 
the instructions for where in the window the program would like things to go (explicitly, or more 
often, relative to other widgets), and then actually put them in the window. 


In doing so, the geometry manager has to balance a number of different constraints: 


+ The widgets may have a "natural" size (e.g. the natural width of a label would normally be 
determined by the text and font in it), but the toplevel all these different widgets are trying to 
fit into isn't big enough to accommodate them; the geometry manager must decide which 
widgets to shrink to fit, by how much, etc. 

e Ifthe toplevel window is bigger than the natural size of all the widgets, how is the extra 
space used? Is it just used for extra space between widgets, and if so, how is that space 
distributed? Is it used to make certain widgets bigger than they normally want to be? 

e Ifthe toplevel window is resized, how does the size and position of the widgets in it change? 
Will certain areas (e.g. a text entry area) expand or shrink, while other parts stay the same 
size, or is the area distributed differently? Do certain widgets have a minimum (or 
maximum) size that you want to avoid going under (over)? 

e How can widgets in different parts of the user interface be aligned with each other, to 
present a clean layout and match platform guidelines to do with inter-widget spacing? 

e For a complex user interface, which may have many frames nested in other frames nested in 
the window (etc.), how can all the above be accomplished, trading off the conflicting 
demands of different parts of the entire user interface? 


How it Works 


Geometry management in Tk relies on the concept of master and slave widgets. A master is a 
widget, typically a toplevel window or a frame, which will contain other widgets, which are called 
slaves. You can think of a geometry manager as taking control of the master widget, and deciding 
what will be displayed within. 


The geometry manager will ask each slave widget for its natural size, or how large it would ideally 
like to be displayed. It then takes that information and combines it with any parameters provided by 
the program when it asks the geometry manager to manage that particular slave widget. In our 
example, we passed grid a "Column" and "row" number for each widget, which indicated the 
relative position of the widget with respect to others, and also a "sticky" parameter to suggest 
how the widget should be aligned or possibly stretched. We also used "columnconfigure"” and 
"rowconfigure" to indicate the columns and rows we'd like to have expand if there is extra 
space available in the window. Of course, all these parameters are specific to grid; other geometry 
managers would use different ones. 


The geometry manager takes all the information about the slaves, as well as the information about 
how large the master is, and uses its internal algorithms to determine the area each slave will be 
allocated (if any!). The slave is then responsible for drawing etc. within that particular rectangle. 
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And of course, any time the size of the master changes (e.g. because the toplevel window was 
resized), the natural size of a slave changes (e.g. because we've changed the text in a label), or any 
of the geometry manager parameters change (e.g. like "row", "column", or "sticky") we 
repeat the whole thing. 


This all works recursively as well. In our example, we had a content frame inside the toplevel 
window, and then a number of other controls in the content frame. We therefore had a geometry 
manager working on two different masters. At the outer level, the toplevel window was the master, 
and the content frame was the slave. At the inner level, the content frame was the master, with each 
of the other widgets being slaves. So the same widget can be both a master and a slave. This 
hierarchy can of course also be nested much more deeply. 


While each master can have only one geometry manager (e.g. grid), it's entirely possible for 
different masters to have different geometry managers; while grid is generally used, others may 
make sense for a particular layout used in one part of your user interface. Also, we've been making 
the assumption that slave widgets are the immediate children of their master in the widget hierarchy. 
While this is usually the case, and mostly there's no good reason to do it any other way, it's also 
possible (with some restrictions) to get around this. 


Event Handling 


In Tk, as in most other user interface toolkits, there is an event loop which receives events from the 
operating system. These are things like button presses, keystrokes, mouse movement, window 
resizing, and so on. 


Generally, Tk takes care of managing this event loop for you. It will figure out what widget the 
event applies to (did the user click on this button? if a key was pressed, which textbox had the 

focus?), and dispatch it accordingly. Individual widgets know how to respond to events, so for 

example a button might change color when the mouse moves over it, and revert back when the 
mouse leaves. 


Command Callbacks 


Often though you want your program to handle particular events, for example doing something 
when a button is pushed. For those events that are pretty much essential to customize (what good is 
a button without something happening when you press it?), the widget will provide a callback as a 
widget configuration option. We saw this in the example with the "Command" option of the button. 


Callbacks in Tk tend to be simpler than in toolkits used with compiled languages (where a callback 
must generally be directed at a procedure with a certain set of parameters or an object method with 
a certain signature). Instead, the callback is just a normal bit of code that the interpreter evaluates. 
While it can be as complex as you want to make it, most times though you'll just want your callback 
to call some other procedure. 
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Event Bindings 

For events that don't have a command callback associated with them, you can use Tk's "bind" to 
Capture any event, and then (like with callbacks) execute an arbitrary piece of code. 

Here is a (silly) example that shows how a label can have bindings set up for it to respond to 
different events, which it does so by just changing what is displayed in the label. 


from tkinter import * 
from tkinter import ttk 


root = Tk() 

1 =ttk.Label(root, text="Starting...") 

1.grid() 

1.bind('<Enter>', lambda e: 1.configure(text='Moved mouse inside')) 
1.bind('<Leave>', lambda e: 1.configure(text='Moved mouse outside' )) 
1.bind('<1>', lambda e: 1.configure(text='Clicked left mouse button')) 
1.bind('<Double-1>', lambda e: 1.configure(text='Double clicked')) 
1.bind('<B3-Motion>', lambda e: 1.configure(text='right button drag to %d,%d' % 


(e.x, e.y))) 
root.mainloop() 


The first three event bindings are pretty straightforward, just looking at simple events. The double 
click binding introduces the idea of an event modifier; in this case we want to trigger the event on a 
left mouse click (the 1"), but only when it's a double click (the "Double -""). 


The last binding also uses a modifier: capture mouse movement ("Motion"), but only when the 
right mouse button ("B3") is held down. This binding also shows an example of how to use event 
parameters, through the use of percent substitutions. Many events, such as mouse clicks or 
movement have as parameters additional information like the current position of the mouse. These 
percent substitutions let you capture them so they can be used in your script. 


Tkinter expects you to provide a function as the event callback, whose first argument is an event 
object representing the event that triggered the callback. It's usually not worth the bother of defining 
regular named functions for one-off callbacks such as in this example, so we've just used Python's 
anonymous functions via lambda. The earlier feet to meters example used a regular defined function 
(calculate). 


For a complete description of all the different event names, modifiers, and the different event 
parameters that are available with each, the best place to look is the "bind" command reference. 


Virtual Events 


Beyond the low-level operating system events like mouse clicks and window resizes, many widgets 
generate higher level events called virtual events. For example, a listbox widget will generate a 
"ListboxSelect" virtual event anytime the selection changes, regardless of whether that was 
because the user clicked on an item, moved to it with the arrow keys, or whatever. This avoids the 
problem of setting up multiple, possibly platform-specific event bindings to capture the change. 
Virtual events for a widget, if any, will be listed in the widget's documentation. 
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Multiple Bindings 


Widgets can actually have a number of different event bindings trigger for a single event. Normally, 
events can be set up for: the individual widget itself, all widgets of a certain class (e.g. buttons), the 
toplevel window containing the widget, and all widgets in the application. Each of these will fire in 
sequence. 


We saw this in our example when we set up a binding for the Return key on the toplevel window, 
and that applied to every widget within that window. 


The default behavior of each widget class in Tk is itself defined with script-level event bindings, 
and so can be introspected and modified to alter the behavior of all widgets of a certain class. You 
can even completely modify the handling of this multiple sequence of events for each widget; see 


the "bindtags" command reference if you're curious. 


Basic Widgets 


This chapter introduces you to the basic Tk widgets that you'll find in just about any user interface: 
frames, labels, buttons, checkbuttons, radiobuttons, entries and comboboxes. By the end, you'll 
know how to use all the widgets you'd ever need for a typical fill-in form type of user interface. 


This chapter (and those following that discuss more widgets) are meant to be read in order. Because 
there is so much commonality between many widgets, we'll introduce certain concepts in an earlier 
widget that will also apply to a later one. Rather than going over the same ground multiple times, 
we'll just refer back to when the concept was first introduced. 


At the same time, each widget will also refer to the widget roundup page for the specific widget, as 
well as the reference manual page, so feel free to jump around a bit too. 


Frame 


e Widget Roundup 
e Reference Manual 


A frame is a widget that displays just as a simple rectangle. Frames are primarily used as a 
container for other widgets, which are under the control of a geometry manager such as grid. 
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Mac OS X Windows Linux 
Frame Widgets 
Frames are created using the ttk. Frame function: 


frame = ttk.Frame(parent) 
Frames can take several different configuration options which can alter how they are displayed. 


Requested Size 

Like any other widget, after creation it is added to the user interface via a (parent) geometry 
manager. Normally, the size that the frame will request from the geometry manager will be 
determined by the size and layout of any widgets that are contained in it (which are under the 
control of the geometry manager that manages the contents of the frame itself). 


If for some reason you want an empty frame that does not contain other widgets, you should instead 
explicitly set the size that the frame will request from its parent geometry manager using the 
"width" and/or "height" configuration options (otherwise you'll end up with a very small 
frame indeed). 

Normally, distances such as width and height are specified just as a number of pixels on the screen. 
You can also specify them via one of a number of suffixes. For example, "350" means 350 pixels, 
"350c" means 350 centimeters, "350i" means 350 inches, and "350p" means 350 printer's 
points (1/72 inch). 


Padding 


The "padding" configuration option is used to request extra space around the inside of the 
widget; this way if you're putting other widgets inside the frame, there will be a bit of a margin all 
the way around. A single number specifies the same padding all the way around, a list of two 
numbers lets you specify the horizontal then the vertical padding, and a list of four numbers lets you 
specify the left, top, right and bottom padding, in that order. 


frame['padding'] = (5,10) 


Borders 


You can display a border around the frame widget; you see this a lot where you might have a part of 
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the user interface looking "sunken" or "raised" in relation to its surroundings. To do this, you need 
to set the "borderwidth" configuration option (which defaults to 0, so no border), as well as the 
"relief" option, which specifies the visual appearance of the border: "flat" (default), 
"raised", "sunken", "solid", "ridge", or "groove". 


frame[ 'borderwidth'] = 2 
frame['relief'] = 'sunken' 


Changing Styles 
There is also a "style" configuration option, which is common to all of the themed widgets, 


which can let you control just about any aspect of their appearance or behavior. This is a bit more 
advanced, so we won't go into it right now. 


Styles mark a sharp departure from the way most aspects of a widget's visual appearance are 
changed in the "classic" Tk widgets. While in classic Tk you could provide a wide range of options 
to finely control every aspect of behavior (foreground color, background color, font, highlight 
thickness, selected foreground color, padding, etc.), in the new themed widgets these changes are 
done by changing styles, not adding options to each widget. 


As such, many of the options you may be familiar with in certain widgets are not present in their 
themed version. Given that overuse of such options was a key factor undermining the appearance of 
Tk applications, especially when moved across platforms, transitioning to themed widgets provides 
an opportune time to review and refine if and how such appearance changes are made. 


Label 
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A label is a widget that displays text or images, typically that the user will just view but not 
otherwise interact with. Labels are used for such things as identifying controls or other parts of the 
user interface, providing textual feedback or results, etc. 


Your Name: >” 4 Your Name: a Your Name: >” 4 


Figure 1. Figure 1. Figure 1. 
Pretty Picture. Pretty Picture. Pretty Picture. 
Name must not be blank. Name must not be blank. Name must not be blank. 
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Label Widgets 


Labels are created using the ttk. Label function, and typically their contents are set up at the 
same time: 
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label = ttk.Label(parent, text='Full name:') 


Like frames, labels can take several different configuration options which can alter how they are 
displayed. 


Displaying Text 
The "text" configuration option shown above when creating the label is the most commonly 


used, particularly when the label is purely decorative or explanatory. You can of course change this 
option at any time, not only when first creating the label. 


You can also have the widget monitor a variable in your script, so that anytime the variable changes, 
the label will display the new value of the variable; this is done with the "textvariable" 
option: 


resultsContents = StringVar() 
label['textvariable'] = resultsContents 
resultsContents.set('New value to display') 


Tkinter only allows you to attach to an instance of the "StringVar" class, which contains all the 
logic to watch for changes, communicate them back and forth between the variable and Tk, and so 
on. You need to read or write the current value using the "get" and "set" methods. 


Displaying Images 

You can also display an image in a label instead of text; if you just want an image sitting in your 
interface, this is normally the way to do it. We'll go into images in more detail in a later chapter, but 
for now, let's assume you want to display a GIF image that is sitting in a file on disk. This is a two- 
step process, first creating an image "object", and then telling the label to use that object via its 
"image" configuration option: 

image = PhotoImage(file='myimage.gif') 

label['image'] = image 

You can use both an image and text, as you'll often see in toolbar buttons, via the "Compound" 
configuration option. The default value is "none", meaning display only the image if present, 
otherwise the text specified by the "text" or "textvariable" options. Other options are 
"text" (text only), "image" (image only), "Center" (text in center of image), "top" (image 
above text), "left", "bottom", and "right". 


Layout 


While the overall layout of the label (i.e. where it is positioned within the user interface, and how 
large it is) is determined by the geometry manager, there are several options that can help you 
control how the label will be displayed within the box the geometry manager gives it. 


If the box given to the label is larger than the label requires for its contents, you can use the 
"anchor" option to specify what edge or corner the label should be attached to, which would 
leave any empty space in the opposite edge or corner. Possible values are specified as compass 
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directions: "n" (north, or top edge), "ne", (north-east, or top right corner), "e", "se", "s", 


"sw", "w", "nw" or "center". 


Labels can be used to display more than one line of text. This can be done by embedding carriage 
returns ("An") in the "text"/"textvariable" string. You can also let the label wrap the 
string into multiple lines that are no longer than a given length (with the size specified as pixels, 
centimeters, etc.), by using the "wraplength" option. 


Multi-line labels are a replacement for the older "Message" widgets in classic Tk. 


You can also control how the text is justified, by using the "justify" option, which can have the 
values "left", "center" or "right". If you only have a single line of text, this is pretty much 


the same as just using the "anchor" option, but is more useful with multiple lines of text. 


Fonts, Colors and More 

Like with frames, normally you don't want to touch things like the font and colors directly, but if 
you need to change them (e.g. to create a special type of label), this would be done via creating a 
new style, which is then used by the widget with the "style" option. 


Unliked most themed widgets, the label widget also provides explicit widget-specific options as an 
alternative; again, you'd use this only in special one-off cases, when using a style didn't necessarily 
make sense. 


You can specify the font used to display the label's text using the "font" configuration option. 
While we'll go into fonts in more detail in a later chapter, here are the names of some predefined 
fonts you can use: 


TkDefaultFont The default for all GUI items not otherwise specified. 
TkTextFont Used for entry widgets, listboxes, etc. 

TkFixedFont A standard fixed-width font. 

TkMenuFont The font used for menu items. 

TkHeadingFont The font typically used for column headings in lists and tables. 
TkCaptionFont A font for window and dialog caption bars. 
TkSmallCaptionFont A smaller caption font for subwindows or tool dialogs 
TkIconFont A font for icon captions. 

TkTooltipFont A font for tooltips. 


Because the choice of fonts is so platform specific, be careful of hardcoding them (font families, 
sizes, etc.); this is something else you'll see in a lot of older Tk programs that can make them look 


ugly. 

The foreground (text) and background color can also be changed via the "foreground" and 
"background" options. Colors are covered in detail later, but you can specify these as either 
color names (e.g. "red") or hex RGB codes (e.g. "#FF340a"). 


Labels also accept the "relief" option that was discussed for frames. 
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Button 
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A button, unlike a frame or label, is very much designed for the user to interact with, and in 
particular, press to perform some action. Like labels, they can display text or images, but also have 
a whole range of new options used to control their behavior. 


[omy ] 


| Okay] 


Cancel 
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Button Widgets 


Buttons are created using the ttk. Button function, and typically their contents and command 
callback are set up at the same time: 


button = ttk.Button(parent, text='Okay', command=submitForm) 


As with other widgets, buttons can take several different configuration options which can alter their 
appearance and behavior. 


Text or Image 


Buttons take the same "text", "textvariable" (rarely used), "image" and "compound" 
configuration options as labels, which control whether the button displays text and/or an image. 


Buttons have a "default" option, which tells Tk that the button is the default button in the user 
interface (i.e. the one that will be invoked if the user hits Enter or Return). Some platforms and 
styles will draw this with a different border or highlight. Set the option to "active" to specify 
this is a default button; the regular state is "normal". Note that setting this option doesn't create 
an event binding that will make the Return or Enter key activate the button; that you have to do 
yourself. 
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The Command Callback 


The "command" option is used to provide an interface between the button's action and your 
application. When the user clicks the button, the script provided by the option is evaluated by the 
interpreter. 


You can also ask the button to invoke the command callback from your application. This is useful 
so that you don't need to repeat the command to be invoked several times in your program; so you 
know if you change the option on the button, you don't need to change it elsewhere too. 


button.invoke() 


Button State 
Buttons and many other widgets can be in a normal state where they can be pressed, but can also be 


put into a disabled state, where the button is greyed out and cannot be pressed. This is done when 
the button's command is not applicable at a given point in time. 


All themed widgets carry with them an internal state, which is a series of binary flags. You can set 
or clear these different flags, as well as check the current setting using the "state" and 
"instate" methods. Buttons make use of the "disabled" flag to control whether or not the 
user can press the button. For example: 


button.state(['disabled']) # set the disabled flag, disabling the 
button 

button.state(['!disabled']) # clear the disabled flag 
button.instate(['disabled']) # return true if the button is disabled, 
else false 

button.instate(['!disabled']) # return true if the button is not 
disabled, else false 

button.instate(['!disabled'], cmd) # execute 'cmd' if the button is not 
disabled 


Note that these commands accept an array of state flags as their argument. 


Using "state"/"instate" replaces the older "state" configuration option (which took the 
values "normal" or "disabled”). This configuration option is actually still available in Tk 8.5, 
but "write-only", which means that changing the option calls the appropriate "state" command, 
but other changes made using the "state" command are not reflected in the option. This is only 
for compatibility reasons; you should change your code to use the new state vector. 


The full list of state flags available to themed widgets is: "active", "disabled", "focus", 
"oressed", "selected", "background", "readonly", "alternate", and 
"invalid". These are described in the themed widget reference; not all states are meaningful for 


all widgets. It's also possible to get fancy in the "State" and "instate" methods and specify 
multiple state flags at the same time. 
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Checkbutton 
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A checkbutton is like a regular button, except that not only can the user press it, which will invoke 
a command callback, but it also holds a binary value of some kind (i.e. a toggle). Checkbuttons are 
used all the time when a user is asked to choose between e.g. two different values for an option. 


| Frognificate ("| Frognificate l Frognificate 
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Checkbutton Widgets 


Checkbuttons are created using the ttk. Checkbutton function, and typically set up at the same 
time: 


measureSystem = StringVar() 

check = ttk.Checkbutton(parent, text='Use Metric', 
command=metricChanged, variable=measureSystem, 
onvalue='metric', offvalue='imperial' ) 


Checkbuttons use many of the same options as regular buttons, but add a few more. The "text", 
"textvariable", "image", and "Compound" options control the display of the label (next 
to the check box itself), and the "state" and "instate" methods allow you to manipulate the 
"disabled" state flag to enable or disable the checkbutton. Similarly, the "Command" option 
lets you specify a script to be called everytime the user toggles the checkbutton, and the "invoke" 
method will also execute the same callback. 


Widget Value 

Unlike buttons, checkbuttons also hold a value. We've seen before how the "textvariable" 
option can be used to tie the label of a widget to a variable in your program; the "variable" 
option for checkbuttons behaves similarly, except it is used to read or change the current value of 
the widget, and updates whenever the widget is toggled. By default, checkbuttons use a value of 
"1" when the widget is checked, and "©" when not checked, but these can be changed to just 
about anything using the "Onvalue" and "of fvalue" options. 


What happens when the linked variable contains neither the on value or the off value (or even 
doesn't exist)? In that case, the checkbutton is put into a special "tristate" or indeterminate mode; 
you'll sometimes see this in user interfaces where the checkbox holds a single dash rather than 
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being empty or holding a check mark. When in this state, the state flag "alternate" is set, so 
you can check for it with the "instate" method: 


check.instate(['alternate']) 


Because the checkbutton won't automatically set (or create) the linked variable, your program needs 
to make sure it sets the variable to the appropriate starting value. 


Radiobutton 
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A radiobutton lets you choose between one of a number of mutually exclusive choices; unlike a 
checkbutton, it is not limited to just two choices. Radiobuttons are always used together in a set, and 
are a good option when the number of choices is fairly small, e.g. 3-5. 
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Radiobutton Widgets 


Radiobuttons are created using the ttk.Radiobutton function, and typically as a set: 


phone = StringVar() 

home = ttk.Radiobutton(parent, text='Home', variable=phone, value='home' ) 
office = ttk.Radiobutton(parent, text='Office', variable=phone, value='office' ) 
cell = ttk.Radiobutton(parent, text='Mobile', variable=phone, value='cell') 


Radiobuttons share most of the same configuration options as checkbuttons. One exception is that 
the "onvalue" and "offvalue" options are replaced with a single "value" option. Each of 
the radiobuttons of the set will have the same linked variable, but a different value; when the 
variable has the given value, the radiobutton will be selected, otherwise unselected. When the linked 
variable does not exist, radiobuttons also display a "tristate" or indeterminate, which can be checked 
via the "alternate" state flag. 


Entry 
e Widget Roundup 
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An entry presents the user with a single line text field that they can use to type in a string value. 
These can be just about anything: their name, a city, a password, social security number, and so on. 


http: //www.tkdocs.com http://www.tkdocs.com |http://www.tkdocs.com 
RARA [arenas 
Guelph | 


Mac OS X Windows Linux 
Entry Widgets 
Entries are created using the ttk. Entry function: 


username = StringVar() 
name = ttk.Entry(parent, textvariable=username) 


A "width" configuration option may be specified to provide the number of characters wide the 
entry should be, allowing you for example to provide a shorter entry for a zip or postal code. 


We've seen how checkbutton and radiobutton widgets have a value associated with them. Entries do 
as well, and that value is normally accessed through a linked variable specified by the 
"textvariable" configuration option. Note that unlike the various buttons, entries don't have a 
separate text or image beside them to identify them; use a separate label widget for that. 


You can also get or change the value of the entry widget directly, without going through the linked 
variable. The "get" method returns the current value, and the "delete" and "insert" 
methods let you change the contents, e.g. 


print('current value is %s' % name.get()) 
name.delete(0, 'end') # delete between two indices, 0-based 
name.insert(0, 'your name') # insert new text at a given index 


Note that entry widgets do not have a "command" option which will invoke a callback whenever 
the entry is changed. To watch for changes, you should watch for changes on the linked variable. 
See also "Validation", below. 


Passwords 


Entries can be used for passwords, where the actual contents are displayed as a bullet or other 
symbol. To do this, set the "show" configuration option to the character you'd like to display, e.g. 


"mx. 


Widget States 


Like the various buttons, entries can also be put into a disabled state via the "state" command 
(and queried with "instate"). Entries can also use the state flag "readonly"; if set, users 
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cannot change the entry, though they can still select the text in it (and copy it to the clipboard). 
There is also an "invalid" state, set if the entry widget fails validation, which leads us to... 


Validation 


validate (controls overall validation behavior) - none (default), key (on each keystroke, runs before - 
prevalidation), focus/focusin/focusout (runs after.. revalidation), all 

* validatecommand script (script must return 1 or 0) 

* invalidcommand script (runs when validate command returns 0) 

- various substitutions in scripts.. most useful %P (new value of entry), %s (value of entry prior to 
editing) 

- the callbacks can also modify the entry using insert/delete, or modify -textvariable, which means 
the in progress edit is rejected in any case (since it would overwrite what we just set) 

* e validate to force validation now 


Combobox 
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A combobox combines an entry with a list of choices available to the user. This lets them either 
choose from a set of values you've provided (e.g. typical settings), but also put in their own value 
(e.g. for less common cases you don't want to include in the list). 
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Combobox Widgets 


Comboboxes are created using the ttk . Combobox function: 


countryvar = StringVar() 
country = ttk.Combobox(parent, textvariable=countryvar ) 


Like entries, the "textvariable" option links a variable in your program to the current value of 
the combobox. As with other widgets, you should initialize the linked variable in your own code. 
You can also get the current value using the "get" method, and change the current value using the 
"set" method (which takes a single argument, the new value). 


36 


A combobox will generate a "<ComboboxSelected>" virtual event that you can bind to 
whenever its value changes. 


country.bind('<<ComboboxSelected>>', function) 


Predefined Values 


You can provide a list of values the user can choose from using the "values" configuration 
option: 


country['values'] = ('USA', 'Canada', 'Australia') 


If set, the "readonly" state flag will restrict the user to making choices only from the list of 
predefined values, but not be able to enter their own (though if the current value of the combobox is 
not in the list, it won't be changed). 


If you're using the combobox in "readonly" mode, I'd recommend that when the value changes (i.e. 
on a ComboboxSelected event), that you call the "selection clear" method. It looks a bit odd 
visually without doing that. 


As a complement to the "get" and "set" methods, you can also use the "current" method to 
determine which item in the predefined values list is selected (call "current" with no arguments, 
it will return a 0-based index into the list, or -1 if the current value is not in the list), or select one of 
the items in the list (call "current" with a single 0-based index argument). 


Want to associate some other value with each item in the list, so that your program can refer to 
some actual meaningful value, but it gets displayed in the combobox as something else? You'll want 
to have a look at the section entitled "Keeping Extra Item Data" when we get to the discussion of 
listboxes in a couple of chapters from now. 


The Grid Geometry Manager 


We'll take a bit of a break from talking about different widgets (what to put onscreen), and focus 
instead on geometry management (where to put it). We introduced the general idea of geometry 
management in the "Tk Concepts" chapter; here, we focus on one specific geometry manager: grid. 


As you've seen, grid lets you layout widgets in columns and rows. If you're familiar with using 
HTML tables to do layout, you'll feel right at home here. This chapter describes the various ways 
you can tweak grid to give you all the control you need for your user interface. 


Grid is one of several geometry managers available in Tk, but it's mix of power, flexibility and ease 
of use, along with its natural fit with today's layouts (that rely on alignment of widgets) make it the 
best choice for general use. There are other geometry managers: "pack" is also quite powerful, but 
harder to use and understand; "place" gives you complete control of positioning each element; we'll 
see even widgets like paned windows, notebooks, canvas and text can act as geometry managers. 


Grid was first introduced to Tk in 1996, several years after Tk became popular, and took a while to 
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catch on. Before that, developers had always used "pack" to do constraint-based geometry 
management. When grid came out, many developers kept using pack, and you'll still find it used in 
many Tk programs and documentation. While there's nothing technically wrong with it, the 
algorithm's behavior is often hard to understand. More importantly, because the order that widgets 
are packed is significant in determining layout, modifying existing layouts can be more difficult. 


Grid has all the power of pack, generally produces nicer layouts (because it makes it easy to align 
widgets both horizontally and vertically), and is easier to learn and use. Because of that, we think 
grid is the right choice for most developers most of the time. Start your new programs using grid, 
and switch old ones to grid as you're making changes to an existing user interface. 


The reference documentation for grid provides an exhaustive description of grid, its behaviors and 
all options. 


Columns and Rows 


Using grid, widgets are assigned a "column" number and a "row" number, which indicates their 
relative position to each other. All widgets in the same column will therefore be above or below 
each other, while those in the same row will be to the left or right of each other. 


Column and row numbers must be integers, with the first column and row starting at 0. You can 
leave gaps in column and row numbers (e.g. column 0, 1, 2, 10, 11, 12, 20, 21), which is handy if 
you plan to add more widgets in the middle of the user interface at a later time. 


The width of each column (or height of each row) depends on the width or height of the widgets 
contained within the column or row. This means when sketching out your user interface, and 
dividing it into rows and columns, you don't need to worry about each column or row being equal 
width. 


Spanning Multiple Cells 


Widgets can take up more than a single cell in the grid; to do this, you'll use the "Columnspan" 
and "rowspan" options when gridding the widget. These are analogous to the "colspan" and 
"rowspan" attribute of HTML tables. 


Here is an example of creating a user interface that has multiple widgets, some that take up more 
than a single cell. 
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gridexample1.tcl 


Gridding multiple widgets 


from tkinter import * 
from tkinter import ttk 


root = Tk() 


content = ttk.Frame(root) 

frame = ttk.Frame(content, borderwidth=5, relief="sunken", width=200, 
height=100) 

namelbl = ttk.Label(content, text="Name") 

name = ttk.Entry(content) 


onevar = Booleanvar() 
twovar = BooleanVar() 
threevar = BooleanVar() 


onevar.set(True) 
twovar.set(False) 
threevar.set(True) 


one = ttk.Checkbutton(content, text="0ne", variable=onevar, onvalue=True) 
two = ttk.Checkbutton(content, text="Two", variable=twovar, onvalue=True) 
three = ttk.Checkbutton(content, text="Three", variable=threevar, onvalue=True) 


ok = ttk.Button(content, text="Okay") 
cancel = ttk.Button(content, text="Cancel") 


content.grid(column=0, row=0) 

frame.grid(column=0, row=0, columnspan=3, rowspan=2) 
namelbl.grid(column=3, row=0, columnspan=2) 
name.grid(column=3, row=1, columnspan=2) 
one.grid(column=0, row=3) 

two.grid(column=1, row=3) 

three.grid(column=2, row=3) 

ok.grid(column=3, row=3) 

cancel.grid(column=4, row=3) 


root .mainloop( ) 


Layout within the Cell 


Because the width of a column (and height of a row) depends on all the widgets that have been 
added to it, the odds are that at least some widgets will have a smaller width or height than has been 
allocated for the cell its been placed in. So the question becomes, where exactly should it be put 
within the cell? 


By default, if a cell is larger than the widget contained in it, the widget will be centered within it, 
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both horizontally and vertically, with the master's background showing in the empty space around it. 
The "sticky" option can be used to change this default behavior. 


The value of the "sticky" option is a string of 0 or more of the compass directions "nsew", 
specifying which edges of the cell the widget should be "stuck" to. So for example, a value of "n" 
(north) will jam the widget up against the top side, with any extra vertical space on the bottom; the 
widget will still be centered horizontally. A value of "nw" (north-west) means the widget will be 
stuck to the top left corner, with extra space on the bottom and right. 


In Tkinter, you can also specify this as a list, containing any of N, S, E and W. 


Specifying two opposite edges, such as "we" (west, east) means that the widget will be stretched, 
in this case so it is stuck both to the left and right edge. So the widget will then be wider than its 
"ideal" size. Most widgets have options that can control how they are displayed if they are larger 
than needed. For example, a label widget has an "anchor" option which controls where the text 
of the label will be positioned. 


If you want the widget to expand to fill up the entire cell, grid it with a sticky value of "nsew" 
(north, south, east, west) meaning it will stick to every side. 


Handling Resize 


If you've taken a peek below and added the extra "sticky" options to our example, when you try 
it out you'll notice things still don't look quite right (the entry is lower on the screen then we'd 
want), and things are even worse if you try to resize the window — nothing moves at all! 


It looks like "sticky" may tell Tk how to react if the cell's row or column does resize, but doesn't 
actually say that the row or columns should resize if extra room becomes available. Let's fix that. 


Every column and row has a "weight" grid option associated with it, which tells it how much it 
should grow if there is extra room in the master to fill. By default, the weight of each column or row 
is 0, meaning don't expand to fill space. 


For the user interface to resize then, we'll need to give a positive weight to the columns we'd like to 
expand. This is done using the "Columnconfigure" and "rowconfigure" methods of grid. 
If two columns have the same weight, they'll expand at the same rate; if one has a weight of 1, 
another of 3, the latter one will expand three pixels for every one pixel added to the first. 


Both "columnconfigure" and "rowconfigure" also take a "minsize" grid option, 
which specifies a minimum size which you really don't want the column or row to shrink beyond. 


Padding 


Normally, each column or row will be directly adjacent to the next, so that widgets will be right 
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next to each other. This is sometimes what you want (think of a listbox and its scrollbar), but often 
you want some space between widgets. In Tk, this is called padding, and there are several ways you 
can choose to add it. 


We've already actually seen one way, and that is using a widget's own options to add the extra space 
around it. Not all widgets have this, but one that does is a frame; this is useful because frames are 
most often used as the master to grid other widgets. The frame's "padding" option lets you 
specify a bit of extra padding inside the frame, whether the same amount for each of the four sides, 
or even different for each. 


A second way is using the "padx" and "pady" grid options when adding the widget. As you'd 
expect, "padx" puts a bit of extra space to the left and right of the widget, while "pady" adds 
extra space top and bottom. A single value for the option puts the same padding on both left and 
right (or top and bottom), while a two value list lets you put different amounts on left and right (or 
top and bottom). Note that this extra padding is within the grid cell containing the widget. 


If you want to add padding around an entire row or column, the '"Columnconfigure" and 
"rowconfigure" methods accept a "pad" option, which will do this for you. 


Let's add the extra sticky, resizing, and padding behavior to our example (additions in bold). 


from tkinter import * 
from tkinter import ttk 


root = Tk() 


content = ttk.Frame(root, padding=(3,3,12,12)) 

frame = ttk.Frame(content, borderwidth=5, relief="sunken", width=200, 
height=100) 

namelbl = ttk.Label(content, text="Name") 

name = ttk.Entry(content) 


onevar BooleanVar ( ) 
twovar BooleanVar ( ) 
threevar = BooleanVar() 


onevar.set(True) 
twovar.set(False) 
threevar.set(True) 


one = ttk.Checkbutton(content, text="0ne", variable=onevar, onvalue=True) 

two = ttk.Checkbutton(content, text="Two", variable=twovar, onvalue=True) 

three = ttk.Checkbutton(content, text="Three", variable=threevar, onvalue=True) 
ok = ttk.Button(content, text="Okay") 

cancel = ttk.Button(content, text="Cancel") 


content.grid(column=0, row=0, sticky=(N, S, E, W)) 

frame.grid(column=0, row=0, columnspan=3, rowspan=2, sticky=(N, S, E, W)) 
namelbl.grid(column=3, row=0, columnspan=2, sticky=(N, W), padx=5) 
name.grid(column=3, row=1, columnspan=2, sticky=(N, E, W), pady=5, padx=5) 
one.grid(column=0, row=3) 

two.grid(column=1, row=3) 

three.grid(column=2, row=3) 

ok.grid(column=3, row=3) 

cancel.grid(column=4, row=3) 
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root .columnconfigure(0, weight=1) 
root.rowconfigure(0, weight=1) 
content.columnconfigure(0, weight=3) 
content.columnconfigure(1, weight=3) 
content.columnconfigure(2, weight=3) 
content.columnconfigure(3, weight=1) 
content.columnconfigure(4, weight=1) 
content.rowconfigure(1, weight=1) 


root.mainloop() 


This looks more promising. Play around with the example to get a feel for the resize behavior. 


600 gridexample2.tcl 
Name 
M One [| Two M Three _ Okay ( Cancel ) | 


Grid example, handling in-cell layout and resize. 


You'll notice the little resize gadget at the very bottom right of the window; while we're just taking 
the easy route and avoiding it with the extra padding, we'll see later how to better take it into 
account using a "sizegrip" widget. 


Additional Grid Features 


As you could see from the grid reference, there are lots of other things you can do with grid. Here 
are a few of the more useful ones. 


Querying and Changing Grid Options 

Like widgets themselves, it's easy to introspect the various grid options, as well as change them; 
setting options when you first grid the widget is just a convenience, and you can certainly change 
them anytime you'd like. 

The "slaves" method will tell you all the widgets that have been gridded inside a master, or 
optionally those within just a certain column or row. The "info" method will give you a list of all 
the grid options for a widget and their values. Finally, the "Configure" method lets you change 
one or more grid options on a widget. 


These are illustrated in this interactive session: 
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>>> content.grid_slaves() 
<map object at 0x00C3F470> 
>>> for w in content.grid_slaves(): print(w) 


.14597008.14622128 
.14597008.14622096 
.14597008.14622064 
.14597008.14622032 
.14597008.14622000 
.14597008.14621872 
.14597008.14621840 
.14597008.14621808 
>>> for w in content.grid_slaves(row=3): print(w) 


.14597008.14622128 
.14597008.14622096 
.14597008.14622064 
.14597008.14622032 
.14597008.14622000 
>>> for w in content.grid_slaves(column=0): print (w) 


.14597008.14622000 

.14597008.14621808 

>>> namelbl.grid_info() 

{'rowspan': '1', ‘column': '3', 'sticky': 'nw', 'ipady': '0', 'ipadx': 'O', 
‘columnspan': '2', 

‘in': <tkinter.ttk.Frame object at Ox00DEBB90>, 'pady': '0', 'padx': '5', 'row!: 
‘@'} 

>>> namelb1.grid_configure(sticky=(E,W)) 

>>> namelbl.grid_info() 

{'rowspan': '1', 'colum': '3', 'sticky': 'ew', 'ipady': '0', 'ipadx': 'O', 
‘columnspan': '2', 

‘in': <tkinter.ttk.Frame object at Ox00DEBB90>, 'pady': 'O', 'padx': '5', 'row!: 
‘o'} 


Internal Padding 


You saw how the "padx" and "pady" grid options added extra space around the outside of a 
widget. There's also a less used type of padding called "internal padding", which is controlled by the 
grid options "ipadx" and "ipady”. 


The difference can be subtle. Let's say you have a frame that's 20x20, and specify normal (external) 
padding of 5 pixels on each side. The frame will request a 20x20 rectangle (its natural size) from 
the geometry manager. Normally, that's what it will be granted, so it'll get a 20x20 rectangle for the 
frame, surrounded by a 5 pixel border. 


With internal padding, the geometry manager will effectively add the extra padding to the widget 
when figuring out its natural size, as if the widget has requested a 30x30 rectangle. If the frame is 
centered, or attached to a single side or corner (using "Sticky"), you'll end up with a 20x20 


frame with extra space around it. If however the frame is set to stretch (i.e. a "Sticky" value of 


we", "ns", or "nwes") it will fill the extra space, resulting in a 30x30 frame, with no border. 


Forget and Remove 


The "forget" method of grid, taking as arguments a list of one or more slave widgets, can be 
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used to remove slaves from the grid they're currently part of. This does not destroy the widget 
altogether, but takes it off the screen, as if it had not been gridded in the first place. You can grid it 
again later, though any grid options you'd originally assigned will have been lost. 


The "remove" method of grid works the same, except that the grid options will be remembered. 


Nested Layouts 


As your user interface gets more complicated, the grid that you're using to organize all your widgets 
can get more and more complicated, and more fine-grained. This can make changing and 
maintaining your program very difficult. 


Luckily, you don't have to manage your entire user interface with a single grid. If you have one area 
of your user interface that is fairly independent of others, create a new frame to hold that area, and 
grid the widgets that are part of that area within that frame. If you had a graphics program of some 
kind with multiple palletes, toolbars, and so on, each one of those areas might be a candidate for 
putting in its own frame. 


In theory, these frames, each with its own grid, can be nested arbitrarily deep, though in practice 
this usually doesn't go beyond a few levels. This can be a big help in modularizing your program. If 
for example you have a pallete of drawing tools, you can create the whole thing in a separate 
procedure, including creating all the component widgets, gridding them together, setting up event 
bindings, and so on. From the point of view of your main program, all it needs to see is the single 
frame widget containing it all. 


Our examples have shown just a hint of this, where a content frame was gridded into the main 
window, and then all the other widgets gridded into the content frame. 


More Widgets 


This chapter carries on introducing several more widgets: listbox, scrollbar, text, progressbar, scale 
and spinbox. Some of these are starting to be a bit more powerful than the basic ones we looked at 
before. Here we'll also see a few instances of using the classic Tk widgets, in instances where there 
isn't (or there isn't a need for) a themed counterpart. 


Listbox 


e Widget Roundup 
e Reference Manual 


A listbox displays a list of single-line text items, usually lengthy, and allows the user to browse 
through the list, selecting one or more. 


Listboxes are part of the classic Tk widgets; there is not presently a listbox in the themed Tk widget 
set. 
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Tk's treeview widget (which is themed) can also be used as a listbox (a one level deep tree), 
allowing you to use icons and styles with the list. It's also likely that a multi-column (table) list 
widget will make it into Tk at some point, based on one of the available extensions. 


Tcl 
Ruby 


Perl 


Lua 
Lisp 
Caml 
Erlang 


Mac OS X Windows Linux 
Listbox Widgets 


Listboxes are created using the Listbox function: 


1 = Listbox(parent, height=10) 


Populating the Listbox Items 


There's an easy way and a hard way to populate and manage all the items that are contained in the 
listbox. 


Here is the easy way. Each listbox has a "Listvariable" configuration option, which allows 
you to link a variable (which must hold a list) to the listbox. Each element of this list is a string 
representing one item in the listbox. So to add, remove, or rearrange items in the listbox, you can 
simply manipulate this variable as you would any other list. Similarly, to find out which item is on 
the third line of the listbox, just look at the third element of the list variable. 


The reason there is a hard way at all is because the "1listvariable" option was only introduced 
in Tk 8.3. Before that, you were stuck with the hard way. Because using the list variable lets you use 
all the standard list operations, it provides a much simpler API, and is certainly an upgrade worth 
considering if you have listboxes doing things the older way. 


The older, harder way to do things is use a set of methods that are part of the listbox widget itself 
that operate on the (internal) list of items: 


e The "insert idx item ?item... ?" method is used to add one or more items to 
the list; "idx" is a 0-based index indicating the position of the item before which the 
item(s) should be added; specify "end" to put the new items at the end of the list. 

e Usethe "delete first ?last?" method to delete one or more items from the list; 
"first" and "last" are indices as per the "insert" method. 

e Usethe "get first ?last?" method to return the contents of a single item at the 
given position, or a list of the items between "first" and "last”. 

¢ The "size" method returns the number of items in the list. 
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Selecting Items 

The first thing you need to decide is whether it is possible for the user to select only a single item at 
a time, or if multiple items can simultaneously be selected. This is controlled by the 
"selectmode" option: the default is only being able to select a single item ("browse"), while a 
selectmode of "extended" allows the user to select multiple items. 


The names "browse" and "extended", again for backwards compatibility reasons, are truly 
awful. This is made worse by the fact that there are two other modes, "single" and 
"multiple" which you should not use (they use an old interaction style that is inconsistent with 
modern user interface and platform conventions). 


To find out which item or items in the listbox the user has currently selected, use the 
"curselection" method, which will return the list of indices of all items currently selected; 
this may be an empty list, and for lists with a selectmode of "browse", will never be longer 
than one item. You can also use the "selection includes index" method to check if the 
item with the given index is currently selected. 


To programmatically change the selection, you can use the "selection clear first ? 
last?" method to deselect either a single item, or any within the range of indices specified. To 
select an item, or all items in a range, use the "selection set first ?last?" method. 
Both of these will not touch the selection of any items outside the range specified. 


If you do change the selection, you should also make sure that the newly selected item is visible to 
the user (i.e. it is not scrolled out of view). To do this, use the "see index" method. 


When the selection is changed by the user, a "<ListboxSelect>" virtual event is generated. 
You can bind to this to take any action you need. Depending on your application, you may also 
want to bind to a double-click "Double - 1" event, and use it to invoke an action with the 
currently selected item. 


Stylizing the List 


Like most of the "classic" Tk widgets, you have immense flexibility in modifying the appearance of 


a listbox. As described in the reference manual, you can modify the font the listbox items are 
displayed in, the foreground (text) and background colors for items in their normal state, when 
selected, when the widget is disabled, and so on. There is also an "itemconfigure" method 
which allows you to change the foreground and background colors of individual items. 


As is often the case, restraint is useful. Generally, the default values will be entirely suitable, and a 
good match for platform conventions. In the example we'll get to momentarily, we'll show how 
restrained use of these options can be put to good effect, in this case displaying alternate lines of the 
listbox in slightly different colors. 


Keeping Extra Item Data 


The "listvariable" (or the internal list, if you're managing things the old way) contains the 
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strings that will be shown in the listbox. It's very often the case though that each string in your 
program is associated with some other data item, and what you're really interested in is not so much 
the string displayed in the listbox, but the associated data item. For example, a listbox containing 
names may be what is presented to the user, but your program is really interested in the user object 
(or id number) that is selected, not the particular name. 


How can we associate this value with the displayed name? Unfortunately, the listbox widget itself 
doesn't offer any facilities, so it's something we'll have to manage separately. There are a couple of 
obvious approaches. First, if the displayed strings are guaranteed unique, you could use a hash table 
to map the names to the associated object. So, given the name you can easily get the associated 
object. This probably wouldn't work well for doing names, but could work for choosing countries 
for example. 


A second approach is to keep a second list, parallel to the list of strings displayed in the listbox, 
which will hold the associated objects. So the first item in the strings list corresponds to the first 
item in the objects list, the second to the second, and so on. Any changes you make in one list 
(insert, delete, reorder) you need to make in the other. You can then easily map from the list item to 
the underlying object, based on their position in the list. 


Example 


Here is a silly example showing these various listbox techniques. We'll have a list of countries 
displayed. Behind the scenes, we have a database (a simple hash table) which contains the 
population of each country, indexed by the two letter country code. We'll be able to select only a 
single country at a time, and as we do so, a status bar will display the population of the country. 
Double-clicking on the list, or hitting the Return key, will send one of several gifts to the selected 
country's head of state (well, not really, but use your imagination). 


rn 


® process Ls JLo fates 
Belgium Send to country's leader: 
Brazil 
Greeting card 
China Flowers 
y O) Nastygram 
France Send Gift 
Greece 
india Sent Nastygram to leader of Canada 
Italy 
The population of Canada (ca) is 33148682 


Country Selector Listbox Example 


from tkinter import * 
from tkinter import ttk 


root = Tk() 

# Initialize our country "databases": 

# - the list of country codes (a subset anyway) 

# - a parallel list of country names, in the same order as the country codes 
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# - a hash table mapping country code to population< 


countrycodes = ('ar', 'au', 'be', 'br', 'ca', 'cn', 'dk', 'fi', 'fr', 'gr', 
‘in', ‘it', '5p', "mx", tnl', 'tno', ‘es', 'se', "ch') 
countrynames = ('Argentina', 'Australia', 'Belgium', 'Brazil', 'Canada', 
'China', 'Denmark', \ 

'Finland', 'France', 'Greece', 'India', 'Italy', 'Japan', 'Mexico', 
'Netherlands', 'Norway', 'Spain', \ 

'Sweden', 'Switzerland') 


cnames = StringVar(value=countrynames) 
populations = {'ar':41000000, 'au':21179211, 'be':10584534, 'br':185971537, \ 
'ca' :33148682, 'cn':1323128240, 'dk':5457415, 'fi':5302000, 
'fr':64102140, 'gr':11147000, M 
'in' :1131043000, 'it':59206382, 'jp':127718000, 'mx':106535000, 
'nl' :16402414, \ 
'no':4738085, 'es':45116894, 'se':9174082, 'ch':7508700} 


# Names of the gifts we can send 
gifts = { 'card':'Greeting card', 'flowers':'Flowers', 'nastygram':'Nastygram'} 


# State variables 

gift = StringVar() 
sentmsg = StringVar() 
statusmsg = StringVar() 


# Called when the selection in the listbox changes; figure out 
# which country is currently selected, and then lookup its country 
# code, and from that, its population. Update the status message 
# with the new population. As well, clear the message about the 
# gift being sent, so it doesn't stick around after we start doing 
# other things. 
def showPopulation(*args): 

idxs = lbox.curselection() 

if len(idxs)==1: 

idx = int(idxs[0]) 


code = countrycodes[idx] 
name = countrynames[idx] 
popn = populations[code] 


statusmsg.set("The population of %s (%s) is %d" % (name, code, popn)) 
sentmsg.set('') 


Called when the user double clicks an item in the listbox, presses 
the "Send Gift" button, or presses the Return key. In case the selected 
item is scrolled out of view, make sure it is visible. 


Figure out which country is selected, which gift is selected with the 
radiobuttons, "send the gift", and provide feedback that it was sent. 
ef sendGift(*args): 
idxs = lbox.curselection() 
if len(idxs)==1: 
idx = int(idxs[0]) 
lbox.see( idx) 
name = countrynames[idx] 
# Gift sending left as an exercise to the reader 
sentmsg.set("Sent %s to leader of %s" % (gifts[gift.get()], name) ) 


OH RE A 


# Create and grid the outer content frame 
c = ttk.Frame(root, padding=(5, 5, 12, 0)) 
c.grid(column=0, row=0, sticky=(N,W,E,S)) 
root.grid_columnconfigure(0, weight=1) 
root.grid_rowconfigure(0,weight=1) 
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# Create the different widgets; note the variables that many 

# of them are bound to, as well as the button callback. 

+ Note we're using the StringVar() 'cnames', constructed from 'countrynames' 
lbox = Listbox(c, listvariable=cnames, height=5) 

1b1 = ttk.Label(c, text="Send to country's leader:") 

ttk.Radiobutton(c, text=gifts['card'], variable=gift, value='card') 
ttk.Radiobutton(c, text=gifts['flowers'], variable=gift, value='flowers') 
g3 = ttk.Radiobutton(c, text=gifts['nastygram'], variable=gift, 
value='nastygram' ) 

send = ttk.Button(c, text='Send Gift', command=sendGift, default='active' ) 
sentlbl = ttk.Label(c, textvariable=sentmsg, anchor='center' ) 

status = ttk.Label(c, textvariable=statusmsg, anchor=wW) 


Q 
N 
IH H 


# Grid all the widgets 

lbox.grid(column=0, row=0, rowspan=6, sticky=(N,S,E,W)) 
lbl.grid(column=1, row=0, padx=10, pady=5) 
g1.grid(column=1, row=1, sticky=W, padx=20) 
g2.grid(column=1, row=2, sticky=W, padx=20) 
g3.grid(column=1, row=3, sticky=W, padx=20) 
send.grid(column=2, row=4, sticky=E) 
sentlbl.grid(column=1, row=5, columnspan=2, sticky=N, pady=5, padx=5) 
status.grid(column=0, row=6, columnspan=2, sticky=(W,E)) 
c.grid_columnconfigure(0, weight=1) 
c.grid_rowconfigure(5, weight=1) 


# Set event bindings for when the selection in the listbox changes, 

# when the user double clicks the list, and when they hit the Return key 
lbox.bind('<<ListboxSelect>>', showPopulation) 

lbox.bind('<Double-1>', sendGift) 

root.bind('<Return>', sendGift) 


# Colorize alternating lines of the listbox 
for i in range(0, len(countrynames),2): 
lbox.itemconfigure(i, background='#fOfOfT' ) 


# Set the starting state of the interface, including selecting the 

# default gift to send, and clearing the messages. Select the first 

# country in the list; because the <<ListboxSelect>> event is only 

# generated when the user makes a change, we explicitly call showPopulation. 
gift.set('card') 

sentmsg.set('') 

statusmsg.set('') 

lbox.selection_set(0) 

showPopulation() 


root.mainloop() 


One obvious thing missing from this example was that while the list of countries could be quite 
long, only part of it fit on the screen at once. To show countries further down in the list you had to 
either drag with your mouse or use the down arrow key. A scrollbar would have been nice. Let's fix 
that. 


Scrollbar 
e Widget Roundup 
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e Reference Manual 


A scrollbar helps the user to see all parts of another widget, whose content is typically much larger 
than what can be shown in the available screen space. 


Mac OS X Windows Linux 
Scrollbar Widgets 


Scrollbars are created using the ttk. Scrollbar command: 


s = ttk.Scrollbar( parent, orient=VERTICAL, command=listbox.yview) 
listbox.configure(yscrollcommand=s.set) 


Unlike in some toolkits, scrollbars are not a part of another widget (e.g. a listbox), but are a separate 
widget altogether. Instead, scrollbars communicate with the scrolled widget by calling methods on 
the scrolled widget; as it turns out, the scrolled widget also needs to call methods on the scrollbar. 


If you're using a recent Linux distribution, you've probably noticed that the scrollbars you see in 
many applications have changed to look more like what you'd see on Mac OS X. This newer look 
isn't supported yet in Tk. 


The "orient" configuration option of scrollbars determines whether it will be used to scroll in 
the "horizontal" or "vertical". You then need to set up the "Command" configuration 
option to communicate with the scrolled widget. This needs to be the method to call on the scrolled 
widget. 


Every widget that can be scrolled vertically includes a method named "yview" (those that can be 
scrolled horizontally have a method named "xview"). As long as this method is present, the 
scrollbar doesn't need to know anything else about the scrolled widget. When the scrollbar is 
manipulated, it will tack on some number of parameters to the method call, indicating how it was 
scrolled, to what position, etc. 


The scrolled widget also needs to communicate back to the scrollbar, telling it what percentage of 
the entire content area is now visible. Besides the yview and/or xview methods, every scrollable 
widget also has a "yscrollcommand" and/or "xscrollcommand" configuration option. This 
is used to specify a method call, which must be the scrollbar's "set" method. Again, additional 
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parameters will be automatically tacked onto the method call. 


If for some reason you want to move the scrollbar to a particular position from within your 
program, you can call the "set first last" method yourself. Pass it two values between 0 
and 1 indicating the start and end percentage of the content area that is visible. 


Example 


Listboxes are one of several types of widgets that are scrollable. Here we'll build a very simple user 
interface, consisting just of a vertically scrollable listbox that takes up the entire window, with just a 


status line at the bottom. 


Line 19 of 100 
Line 20 of 100 
Line 21 of 100 E 
Line 22 of 100 

Line 23 of 100 
Line 24 of 100 
Line 25 of 100 
Line 26 of 100 
Line 27 of 100 
Line 28 of 100 [xi 


Status message here 


Scrolling a Listbox 


from tkinter import * 
from tkinter import ttk 


root = Tk() 
1 = Listbox(root, height=5) 
l.grid(column=0, row=0, sticky=(N,W,E,S)) 
s = ttk.Scrollbar(root, orient=VERTICAL, command=1.yview) 
s.grid(column=1, row=0, sticky=(N,S)) 
l['yscrollcommand'] = s.set 
ttk.Sizegrip().grid(column=1, row=1, sticky=(S,E)) 
root.grid_columnconfigure(0, weight=1) 
root.grid_rowconfigure(0, weight=1) 
for i in range(1,101): 

l.insert('end', 'Line %d of 100' % i) 
root .mainloop( ) 


SizeGrip 


e Widget Roundup 
e Reference Manual 


We actually snuck in one new widget in that last example, the sizegrip. This is the little box at the 
bottom right corner of the window that allows you to resize it. 
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Mac OS X Windows Linux 
SizeGrip Widgets 
SizeGrips are created using the ttk.Sizegrip function: 
ttk.Sizegrip(parent).grid(column=999, row=999, sticky=(S,E)) 
While you'll notice that on some platforms (e.g. Mac OS X), Tk will automatically put the size grip 


there for you, it doesn't hurt to explicitly add it yourself. We'll discuss how to change the window 
size, determine if it's resizable, etc. in a later chapter. 


Platform conventions tend to evolve faster than long-lived open source GUI toolkits. Mac OS X 
10.7 did away with the size grip in the corner, in favour of allowing resizing from any window 
edge, finally catching up with the rest of the world. It's therefore best to check the operating system 
version you're running before adding the sizegrip. 


Text 
e Widget Roundup 


e Reference Manual 


A text widget provides users with an area so that they can enter multiple lines of text. Text widgets 
are part of the classic Tk widgets, not the themed Tk widgets. 


Lorem ipsum dolor Lorem HE Lorem ipsum dolor 

sit amet, donec a CAS, donec a sit amet, donec a 

dignissimos orci dignissimos orci dignissimos orci 

non, nonummy non, nonummy non, nonummy 

tristique sit tristique sit tristique sit — 

metus, velit odio metus, velit odio metus, velit odio 
Mac OS X Windows Linux 

Text Widgets 


Tk's text widget is, along with the canvas widget, one of two uber-powerful widgets that provide 
amazingly deep but easily programmed features. Text widgets have formed the basis for full word 
processors, outliners, web browsers and more. We'll get into some of the advanced stuff in a later 
chapter, but here we'll just show you what you need to use the text widget to capture fairly simple, 
multi-line text input. 
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Text widgets are created using the Text function: 


t = Text(parent, width=40, height=10) 


The "width" and "height" options specify the requested screen size of the text widget, in 
characters and rows respectively. The contents of the text can be arbitrarily large. You can use the 
"wrap" configuration option to control how line wrapping is handled: values are "none" (no 
wrapping, text may horizontally scroll), "char" (wrap at any character), and "word" (wrapping will 
only occur at word boundaries). 


A text widget can be disabled so that no editing can occur; because text is not a themed widget, the 
usual "state" and "instate" methods are not available. Instead, use the configuration option 
"state", setting it to either "disabled" or "normal". 


Scrolling works the same way as in listboxes. The "xscrollcommand" and 
"yscrollcommand" configuration options are available to attach the text widget to horizontal 
and/or vertical scrollbars, and the "Xview" and "yview" methods are available to be called from 
scrollbars. To ensure that a given line is visible (i.e. not scrolled out of view), you can use the "See 
index" method, where index is in the form "line number.character number", e.g. "5.0" for the 
first (0-based) character of line 5 (1-based). 


Contents 

Text widgets do not have a linked variable associated with them, like for example entry widgets do. 
To retrieve the text content for the entire widget, call the method "get 1.0 end"; the "1.0" is 
an index into the text, and means the first character of the first line, and "end" is a shortcut for the 
index of the last character, last line. Other indices could be passed to retrieve smaller ranges of text 
if needed. 


Text can be added to the widget using the "insert index string" method; again index is 
in the form "1ine.char" and marks the character before which text is inserted; use "end" to 
add text to the end of the widget. You can delete a range of text using the "delete start 
end" method, where both start and end are text indices as already described. 


We'll get into the text widget's many additional advanced features in a later chapter. 


Progressbar 


e Widget Roundup 
e Reference Manual 


A progressbar widget provides a way to give feedback to the user about the progress of a lengthy 
operation. This may be done either as a percentage complete display for operations where this can 
be estimated, or a display that changes to indicate the operation is continuing, but without an 
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estimate of completion. 
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Progressbar Widgets 


Progessbar widgets are created using the ttk .Progessbar class: 


p = ttk.Progressbar(parent, orient=HORIZONTAL, length=200, mode='determinate' ) 


The "orient" option may be either "horizontal" or "vertical". The "length" option, 
which represents the longer axis of either horizontal or vertical progressbars, is specified in screen 
units (e.g. pixels). The "mode" configuration option can be set to either "determinate", where 
the progressbar will indicate relative progress towards completion, orto "indeterminate", 
where its not possible to know how far along in the task the program is, but we still want to provide 
feedback that things are still running. 


Determinate Progess 


In determinate mode, you're able to provide more-or-less accurate feedback to the user about how 
far an operation has progressed. To do this, you need to first of all tell the progressbar how many 
"steps" the operation will take, and then as you go along, tell the progressbar how far along the 
operation is. 


You can provide the total number of steps to the progressbar using the "maximum" configuration 
option; this is a floating point number that defaults to 100 (i.e. each step is 1%). To tell the 
progressbar how far along you are in the operation, you will repeatedly change the "value" 
configuration option. So this would start at 0, and then count upwards to the maximum value you 
have set. There are two slight variations on this. First, you can just store the current value for the 
progressbar in a variable linked to it by the progressbar's "variable" configuration option; that 
way, when you change the variable, the progressbar will update. The other alternative is to call the 
progressbar's "step ?amount?" method to increment the value by the given "amount" (defaults 
to 1.0). 


Indeterminate Progress 


Indeterminate mode is for when you're not able to easily know (or estimate) how far along in a long 
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ruming task you actually are, but still want to provide feedback to the user that the operation is still 
ruming (or that your program hasn't crashed). Rather than providing specific values to indicate 
progress along the way, at the start of the operation you'll just call the progressbar's "start" 
method, and at the end of the operation, you'll call its "stop" method. The progressbar will take 
care of the rest. 


Scale 


e Widget Roundup 
e Reference Manual 


A scale widget provides a way for users to choose a numeric value through direct manipulation. 


Mac OS X Windows Linux 
Scale Widgets 
Scale widgets are created using the ttk.Scale function: 


s = ttk.Scale(parent, orient=HORIZONTAL, length=200, from_=1.0, to=100.0) 


Because 'from' is a reserved keyword, you'll need to add a trailing underscore when using it as a 
configuration option. 


In some ways, scale widgets are like progressbars, except they are designed for the user to 
manipulate them. As with progressbars, they should be given an orientation (horizontal or vertical) 
with the "Orient" configuration option, and an optional "length". You should also define the 
range of the number that the scale allows users to choose; to do this, set a floating point number for 
each of the "from" and "to" configuration options. 


There are several different ways you can set the current value of the scale (which must be a floating 
point value between the "from" and "to" values). You can set (or read, to get the current value) 
the scale's "value" configuration option. You can link the scale to a variable using the 
"variable" option. Or, you can call the scale's "set value" method to change the value, or 
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the "get" method to read the current value. 


There is a "command" configuration option, which lets you specify a script to call whenever the 
scale is changed. Tk will automatically append the current value of the scale as a parameter each 
time it invokes this script (we saw a similar thing with extra parameters being added to scrollbar 
callbacks and those on the widgets they scroll). 


As with other themed widgets, you can use the "state disabled", "state !disabled" 
and "instate disabled" methods if you wish to prevent the user from modifying the scale. 


As the scale widget does not display the actual values, you may want to add those as labels. 


Spinbox 


e Widget Roundup 
e Reference Manual 


A spinbox widget allows users to choose numbers (or in fact, items from an arbitrary list). It does 
this by combining an entry-like widget showing the current value with a pair of small up/down 
arrows which can be used to step through the range of possible choices. 


Spinboxes are part of the classic Tk widgets. There is not presently a spinbox in the themed Tk 
widget set. 


That last statement is not entirely accurate. A themed spinbox widget was in fact added in Tk 8.5.9. 
So if your code just assumes 8.5 (as this tutorial does), you can't rely on it. It may be worth 
checking to see if you're running 8.5.9 or higher, and if so, use the themed version. But as with 
other themed widgets, the APT is slightly different than the classic widget. 
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Mac OS X Windows 
Spinbox Widgets 
Spinbox widgets are created using the Spinbox function: 


spinval = StringVar() 
s = Spinbox(parent, from_=1.0, to=100.0, textvariable=spinval) 


Like scale widgets, spinboxes are normally used to let the user choose a number between a certain 
range (specified using the "from" and "to" configuration options), though through a very 
different user interface. You can also specify a "increment", which controls how much the value 
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changes everytime you click the up or down button. 


Like a listbox or combobox, spinboxes can also be used to let the user choose an item from an 
arbitrary list of strings; these can be specified using the "values" configuration option, which 
works in the same was as in comboboxes. Specifying a list of values will override to "from" and 
"to" settings. 


You might be puzzled about when to choose a scale, listbox, combobox, entry or a spinbox, since 
usually several of these can be used for the same types of data. The answer really depends on the 
type of data you want the user to select, platform user interface conventions, and the role the value 
plays in your user interface. 


For example, both a combobox and a spinbox have the benefit of taking up fairly small amounts of 
space, which might make sense for a more peripheral setting, where the primary choice in a user 
interface may warrant the extra space a listbox occupies. Spinboxes don't make much sense when 
items don't have a natural and obvious ordering to them. You should be careful about both 
comboboxes and spinboxes that have too many items in them, which can make it more time 
consuming to select an item. 


Both both a numeric and arbitrary range, there is a "wrap" option which accepts a boolean, and 
determines whether the value should wrap around when it goes beyond the starting or ending 
values. You can also specify a "width" for the entry holding the current value of the spinbox. 


Again there are choices as to how to set or get the current value in the spinbox. Normally, you 
would specify a linked variable with the "textvariable" configuration option; as usual, any 
changes to the variable are reflected in the spinbox, while any changes in the spinbox are reflected 
in the linked variable. As well, the "set value" and "get" methods allow you to set or get the 
value directly. 


You can arranged to be called whenever the spinbox changes using the "Command" configuration 
option. 


The command has a couple of percent substitutions, %s = current value, and %d = up or down. 
Need to figure out the right way to specify this in Ruby. Also need to add stuff about validation. 


Because spinbox is not a themed widget, the "state" and "instate" methods are not 
available. Instead, you can change its state using the "state" configuration option. This may be 
"normal", "disabled" to prevent any changes. 


Menus 


This chapter describes how to handle menubars and popup menus in Tk. For a polished application, 
these are areas you particularly want to pay attention to. Menus need special care if you want your 
application to fit in with other applications on your users' platform. 


Speaking of which, the recommended way to figure out which platform you're running on is: 
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root.tk.call('tk', 'windowingsystem' ) # will return x11, win32 or aqua 


To the best of my knowledge, Tkinter does not provide a direct equivalent to this call. However, as 
you can see from the example, it is possible to execute a Tcl-based Tk command directly, using the 
"tk.call(Q" function available on any Tkinter widget. 


This is probably more useful than examining global variables like tcl_platform or 
RUBY_PLATFORM, and older checks that used these methods should be examined. While in the 
olden days there was a pretty good correlation between platform and windowing system, it's less 
true today. For example, if your platform is identified on Unix, that might mean Linux under X11, 
Mac OS X under Aqua, or even Mac OS X under X11. 


Menubars 


In this section we'll look at menubars: how to create them, what goes in them, how they're used, and 
so on. 


Properly designing a menubar and its set of menus is beyond the scope of this tutorial, but a few 
pieces of advice. First, if you find yourself with a large number of menus, very long menus, or 
deeply nested menus, you may need to rethink how your user interface is organized. Second, many 
people use the menus to explore what the program can do, particularly when they're first learning it, 
so try to ensure major features are accessible by the menus. Finally, for each platform you're 
targeting, become familiar with how applications use menus, and consult the platform's human 
interface guidelines for full details about design, terminology, shortcuts, and much more. This is an 
area you will likely have to customize for each platform. 


You'll notice on some recent Linux distributions that many applications show their menus at the top 
of the screen when active, rather than in the window itself. Tk does not yet support this style of 
menus. 


Menu Widgets and Hierarchy 


e Widget Roundup 
e Reference Manual 


Menus are implemented as widgets in Tk, just like buttons and entries. Each menu widget consists 
of a number of different items in the menu. Items are things like the "Open..." command in a File 
menu, but also separators between other items, and items which open up their own submenu (so- 
called cascading menus). Each of these menu items also has attributes, such as the text to display 
for the item, a keyboard accelerator, and a command to invoke. 


Menus are arranged in a hierarchy. The menubar is itself a menu widget. It has several children 
(submenus) consisting of items like "File", "Edit" and so on. Each of those in turn is a menu 
containing different items, some of which might themselves contain submenus. As you'd expect 
from other things you've seen already in Tk, anytime you have a submenu, it must be created as a 


58 


child of its parent menu. 


Before you Start 


It's important to put the following line in your application somewhere before you start creating 
menus. 


root.option_add('*tearO0ff', FALSE) 


Without it, each of your menus (on Windows and X11) will start with what looks like a dashed line, 
and allows you to "tear off" the menu so it appears in its own window. You really don't want that 
there. 


This is a throw-back to the Motif-style X11 that Tk's original look and feel were based on. Unless 
your application is designed to run on that old box collecting dust in the basement, you really don't 
want to see this, as its not a part of any modern user interface style. 


And we'll all be looking forward to a version of Tk where this backwards compatibility is not 
preserved, and the default is not to have these tear-off menus. 


Creating a Menubar 


In Tk, menubars are associated with individual windows; each toplevel window can have at most 
one menubar. On Windows and X11, this is visually obvious, as the menus are part of each window, 
sitting just below the title bar at the top. 


On Mac OS X though, there is a single menubar along the top of the screen, shared by each 
window. As far as your Tk program is concerned, each window still does have its own menubar; as 
you switch between windows, Tk will automatically take care of making sure that the correct 
menubar is displayed at the top of the screen. If you don't specify a menubar for a particular 
window, Tk will use the menubar associated with the root window; you'll have noticed by now that 
this is automatically created for you when your Tk application starts. 


Because on Mac OS X all windows have a menubar, it's important to make sure you do define one, 
either for each window or a fallback menubar for the root window. Otherwise, you'll end up with 
the "built-in" menubar, which contains menus that are only intended for use when typing commands 
directly into the interpreter. 


To actually create a menubar for a window, we first create a menu widget, and then use the 
window's "menu" configuration option to attach the menu widget to the window. 
win = Toplevel(root ) 


menubar = Menu(win) 
win[ 'menu'] = menubar 


Note that you can use the same menubar for more than one window (i.e. use one menubar as the 

value of the "menu" configuration option for different toplevel windows). This is particularly useful 
on Windows and X11, where you may want a window to include a menu, but don't necessarily need 
to juggle different menus in your application. But remember, if the contents or state of the menubar 
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depend on what's going on in the active window, you'll have to deal with that yourself. 


This is truly ancient history, but menubars used to be done by creating a frame widget containing 
the menu items, and packing it into the top of the window like you would any other widget. 
Hopefully you don't have any code or documentation that still does this. 


Adding Menus 


We now have a menubar, but that's pretty useless without some menus to go in it. So again, we'll 
want to create a menu widget for each menu that will go in the menubar (each one a child of the 
menubar), and then add them all to the menubar. 


menubar = Menu(parent) 

menu_file = Menu(menubar ) 

menu_edit = Menu(menubar ) 

menubar .add_cascade(menu=menu_file, label='File' ) 
menubar .add_cascade(menu=menu_edit, label='Edit') 


Adding Menu Items 
Now that we have a couple of menus in our menubar, it's probably a good time to add a few items to 


each menu. Remember that menu items are part of the menu itself, so we thankfully don't have to 
go and create another menu widget for each one. 


menu_file.add_command(label='New', command=newFile) 
menu_file.add_command(label='Open...', command=openFile) 
menu_file.add_command(label='Close', command=closeFile) 


On Mac OS X, the ellipsis ("...") is actually a special character, which is more tightly spaced than 
three periods in a row. Tk takes care of substituting this character for you automatically. 


So adding menu items to a menu is essentially the same as adding a submenu, but rather than 
adding a menu item of type "cascade", we're adding one of type "command". 


Each menu item has associated with it a number of configuration options, in the same way widgets 
do, though each menu item type has a different set of relevant options. Cascade menu items have a 
"menu" option used to specify the submenu, command menu items have a "Command" option 
used to specify the command to invoke when the item is selected, and both have a "label" option 
to specify the text to display for the item. 


As well as adding items to the end of menus, you can also insert them in the middle of menus via 
the "insert index type ?option value...?" method; here "index" is the position 
(0..n-1) of the item you want to insert before. You can also delete a menu using the "delete 
index" method. 


Types of Menu Items 


We've already seen "command" menu items, which are the common menu items that when 
selected will invoke a command. 
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We've also seen the use of "cascade" menu items, used to add a menu to a menubar. Not 
surprisingly, if you want to add a submenu to an existing menu, you also use a "cascade" menu 
item, in exactly the same way. 


A third type of menu item is the "separator", which produces the dividing line you often see 
between different sets of menu items. 


menu_file.add_separator() 


Finally, there are also "Checkbutton" and "radiobutton" menu items, which behave 
analogously to checkbutton and radiobutton widgets. These menu items have a variable associated 
with them, and depending on the value of that variable, will display an indicator (i.e. a checkmark 
or a selected radiobutton) next to the item's label. 


check = StringVar() 

menu_file.add_checkbutton(label='Check', variable=check, onvalue=1, offvalue=0) 
radio = StringVar() 

menu_file.add_radiobutton(label='One', variable=radio, value=1) 
menu_file.add_radiobutton(label='Two', variable=radio, value=2) 


When the user selects a checkbutton item that is not already checked, it will set the associated 
variable to the value in "Onvalue", while selecting a item that is already checked sets it to the 
value in "of fvalue". Selecting a radiobutton item sets the associated variable to the value in 
"value". Both types of items also react to changes in the associated variable from within other 
parts of your program. 


As with command items, checkbutton and radiobutton menu items do accept a "Command" 
configuration option, that will be invoked when the menu item is selected; the associated variable, 
and hence the menu item's state, is updated before the callback is invoked. 


Radiobutton menu items are not part of the Windows or Mac OS X human interface guidelines, so 
on those platforms the indicator next to the item's label is a checkmark, as it would be for a 
checkbutton item. The semantics still work though; it's a good way to select between multiple items, 
since the display will show one of the items selected (checked). 


Accelerator Keys 


The "accelerator" option is used to indicate the menu accelerator that should be associated 
with this menu. This does not actually create the accelerator, but only displays what it is next to the 
menu item. You still need to create a binding for the accelerator yourself. 


Remember that event bindings can be set on individual widgets, all widgets of a certain type, the 
toplevel window containing the widget you're interested in, or the application as a whole. As menu 
bars are associated with individual windows, normally the event bindings you create will be on the 
toplevel window the menu is associated with. 


Accelerators are very platform specific, not only in terms of which keys are used for what 
operation, but what modifier keys are used for menu accelerators (e.g. on Mac OS X it is the 
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"Command" key, on Windows and X11 it is usually the "Control" key). Example of valid 
accelerator options are "Command -N", "Shift+Ctr1+X", and "Command -Option-B". 
Commonly used modifiers include "Control", "Ctrl", "Option", "Opt", "Alt", "Shift", "Command", 
"Cmd" and "Meta"). 


On Mac OS X, those modifiers will be automatically mapped to the different modifier icons that 
appear in menus. 


More on Item Options 


There are a few more common options for menu items. 


Underline 

While all platforms support keyboard traversal of the menubar via the arrow keys, on Windows and 
X11, you can also use other keys to jump to particular menus or menu items. The keys that trigger 
these jumps are indicated by an underlined letter in the menu item's label. If you want to add one of 
these to a menu item, you can use the "underline" configuration option for the item. The value 
of this option should be the index of the character you'd like underlined (from 0 to the length of the 
string - 1). 


Images 

It is also possible to use images in menu items, either beside the menu item's label, or replacing it 
altogether. To do this, you can use the "image" and "Compound" options, which work just like 
in label widgets. The value for "image" must be a Tk image object, while "Compound" can 
have the values "bottom", "center", "left", "right", "top" or "none". 


State 

It is also possible to disable a menu, so that the user cannot select it. This can be done via the 
"state" option, setting it to a value of "disabled", or a value of "normal" to reenable the 
item. 


Querying and Changing Item Options 

Like most everything in Tk, you can look at or change the value of an item's options at any time. 
Items are referred to via an index. Normally, this is a number (0..n-1) indicating the item's position 
in the menu, but you can also specify the label of the menu item (or in fact, a "glob-style" pattern to 
match against the item's label). 

print( menu_file.entrycget(0, 'label') ) 


menu_file.entryconfigure('Close', state=DISABLED) 
print( menu_file.entryconfigure(0) ) 
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Platform Menus 


Each platform has a few menus that are handled specially by Tk. 


Mac OS X 


You've probably noticed if you've been playing around with the previous examples on Mac OS X, 
that Tk supplies its own default menubar, including a menu named after the program being run (in 
this case, your programming language's shell, e.g. "Wish', 'Python', etc.), a File menu, and standard 
Edit, Windows, and Help menu, all stocked with various menu items. 


You can override this menubar in your own program, but to get the results you want, you'll need to 
follow some particular steps (in some cases, in a particular order). 


Starting at Tk 8.5.13, the handling of special menus on the Mac changed, a result of the underlying 
Tk code switching from the obsolete Carbon API to Cocoa. If you're seeing duplicate menu names, 
missing items, things you didn't put there, etc. review this section carefully. 


The first thing to know is that if you don't specify a menubar for a window (or its parent window, 
e.g. the root window) you'll end up with the default menubar Tk supplies, which unless you're just 
mucking around on your own, is almost certainly not what you want. 


The Application Menu 


If you do supply a menubar, at the time the menubar is attached to the window, if there is not a 
specially named ".apple" menu (see below), Tk will provide a standard application menu, named 
after the binary being run. It will contain an "About Tcl & Tk" item, followed by the standard menu 
items: preferences, the services submenu, hide/show items, and quit. Again, you don't want this. 


If you supply your own ".apple" menu, when the menubar is attached to the window, it will add the 
standard items (preferences and onward) onto the end of any items you have added. Perfect! (Items 
you add after the menubar is attached to the window will appear after the quit item, which, again, 
you don't want.) 


The application menu, which is the one we're dealing with here, is distinct from the apple menu (the 
one with the apple icon, just to the left of the application menu). Despite that we do really mean the 
application menu, in Tk it is still referred to as the "apple" menu. This is a holdover from pre-OS X 
days, when these sorts of items did go in the actual apple menu, and there was no separate 
application menu. 


So in other words, in your program, make sure you: 


1. Create a menubar for each window, or the root window. Do not attach the menubar to the 
window yet! 

2. Add a menu to the menubar named ".apple" which will be used as the application menu. 

3. The title of the menu will automatically be named the same as the application binary; if you 
want to change this, rename (or make a copy of) the binary used to run your script. 

4. Add the items you want to appear at the top of the application menu, i.e. an "About yourapp" 
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item, followed by a separator. 
5. After you have done all this, you can then attach the menubar to your window. 
win = Toplevel(root) 
menubar = Menu(win) 
appmenu = Menu(menubar, name='apple' ) 
menubar .add_cascade(menu=appmenu ) 
appmenu.add_command(label='About My Application' ) 


appmenu.add_separator() 
win[ 'menu'] = menubar 


While normally Tkinter chooses a widget path name for us, here we've had to explicitly provide one 
(‘apple’) using the 'name' option when creating the application menu. 


Handling the Preferences Menu Item 

As you've noticed, the application menu always includes a "Preferences..." menu item; this is 
automatically included. If your application has a preferences dialog, selecting this menu item should 
open it. If your application has no preferences dialog, this menu item should be disabled, which it is 
by default. 


To hook up your preferences dialog, you'll need to define a Tcl procedure named 
"::tk::mac: :ShowPreferences”. This will be called when the Preferences menu item is 
chosen; if the procedure is not defined, the menu item will be disabled. 


def showMyPreferencesDialog(): 
root.createcommand('tk::mac: :ShowPreferences', showMyPreferencesDialog) 


Providing a Help Menu 


Like the application menu, any help menu you add to your own menubar is treated specially on Mac 
OS X. As with the application menu that needed a special name ('.apple”), the help menu must be 
given the name '.help'. Also like the application menu, the help menu should also be added before 
the menubar is attached to the window. 


The help menu will include the standard OS X search box to search help, as well as an item named 
'yourapp Help'. As with the name of the application menu, the name of this item comes from the 
name of the binary running your program and cannot be changed. Similar to how preferences 
dialogs are handled, to respond to this help item, you need to define a Tcl procedure named 

"+ :itk::mac: :ShowHelp". Unlike with preferences, not defining this procedure will generate 


an error, not disable the menu item. 


If you don't want to include help, just don't add a help menu to the menubar, and none will be 
shown. 


Unlike on X11 and earlier versions of Tk on Mac OS X, the Help menu will not automatically be 
put at the end of the menubar, so ensure it is the last menu added. 


You can also add other items to the help menu, which will appear after the application help item. 
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helpmenu = Menu(menubar, name='help' ) 
menubar .add_cascade(menu=helpmenu, label='Help' ) 
root.createcommand('tk::mac::ShowHelp', ...) 


Providing a Window Menu 


On Mac OS X, a 'Window' menu is used to contain items like minimize, zoom, bring all to front, 
etc. It also contains a list of currently open windows. Before that list, other application-specific 
items are sometimes provided. 


By providing a menu named ".window", this standard window menu will be added, and Tk will 
automatically keep it in sync with all your toplevel windows, without any extra code on your part. 
You can also add any application-specific commands to this menu, which will appear before the list 
of your windows. 


windowmenu = Menu(menubar, name='window' ) 
menubar .add_cascade(menu=windowmenu, label='Window' ) 


Other Menu Handlers 


You saw previously how handling certain menu items required you to define Tcl callback 
procedures, in particular for displaying the preferences dialog ('tk::mac::ShowPreferences”) and 
displaying help (‘tk::mac::ShowHelp’). 


There are several other callbacks that you can define, for example to intercept the Quit menu item to 
prompt to save changes, or to be informed when the application is hidden or shown. Here is the 
complete list: 


Called when the 
tk: :mac: :ShowPrefe "Preferences..." 
rences menu item is 

selected. 


Called to display 
main online help 
for the 
application. 


Called when the 
Quit menu item 
Quit is selected, when 
the user is trying 
to shut down the 
system etc. 
Called when 
tk: :mac: :OnHide your application 
has been hidden. 
Called when 
your application 
is shown after 
being hidden. 


tk::mac::OpenAppli Called when 


tk: :mac: :ShowHelp 


tk::mac:: 


tk: :mac: :OnShow 
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your application 
is first opened. 


Called when the 
user "reopens" 
your already- 
running 
application (e.g. 
clicks on it in the 
Dock) 


Called when the 
Finder wants the 
application to 
open one or 
more documents 
tk: :mac: :OpenDocum (e.g. that were 
ent dropped on it). 
The procedure is 
passed a list of 
pathnames of 
files to be 
opened. 
As with 
OpenDocument, 
but the 
documents 
should be printed 
rather than 
opened. 


cation 


tk: :mac: :ReopenApp 
lication 


tk: :mac: :PrintDocu 
ment 


Windows 


On Windows, each window has a "System" menu at the top left of the window frame, with a small 
icon for your application. It contains items like "Close", "Minimize", etc. In Tk, if you create a 
system menu, you can add new items that will appear below the standard items. 


sysmenu = Menu(menubar, name='system' ) 
menubar .add_cascade(menu=sysmenu ) 


While normally Tkinter will choose a widget path name for us, here we've had to explicitly provide 
one with the name 'system'; this is the cue that Tk needs to recognize it as the system menu. 


X11 
On X11, if you create a help menu, Tk will ensure that it is always the last menu in the menubar. 


menu_help = Menu(menubar, name='help' ) 
menubar .add_cascade(menu=menu_help, label='Help' ) 


The widget pathname of the menu must be explicitly provided, in this case with the name "help". 
This can be specified for any Tkinter widget using the 'name' option when creating the widget. 
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Contextual Menus 


Contextual menus ("popup" menus) are typically invoked by a right mouse button click on an object 
in the application. A menu pops up at the location of the mouse cursor, and the user can select from 
one of the items in the menu (or click outside the menu to dismiss it without choosing any item). 


To create a contextual menu, you'll use exactly the same commands you did to create menus in the 
menubar. Typically, you'll create one menu with several command items in it, and potentially some 
cascade menu items and their associated menus. 


To activate the menu, the user will use a contextual menu click, which you will have to bind to. 
That however, can mean different things on different platforms. On Windows and X11, this is the 
right mouse button being clicked (the third mouse button). On Mac OS X, this is either a click of 
the left (or only) button with the control key held down, or a right click on a multi-button mouse. 
Unlike Windows and X11, Mac OS X refers to this as the second mouse button, not the third, so 
that's the event you'll see in your program. 


Most earlier programs that have used popup menus assumed it was only "button 3" they needed to 
worry about. 


Besides capturing the correct contextual menu event, you'll also need to capture the location the 
mouse was clicked. It turns out you need to do this relative to the entire screen (global coordinates) 
and not local to the window or widget you clicked on (local coordinates). The "%X" and "%Y" 
substitutions in Tk's event binding system will capture those for you. 


The last step is simply to tell the menu to popup at the particular location. Here's an example of the 
whole process, using a popup menu on the application's main window. 


from tkinter import * 


root = Tk() 
menu = Menu(root) 
for i in ('One', 'Two', 'Three'): 


menu. add_command(label=i) 
if (root.tk.call('tk', 'windowingsystem')=='aqua'): 
root.bind('<2>', lambda e: menu.post(e.x_root, e.y_root)) 
root.bind('<Control-1>', lambda e: menu.post(e.x_root, e.y_root)) 
else: 
root.bind('<3>', lambda e: menu.post(e.x_root, e.y_root)) 


Windows and Dialogs 


Everything we've done up until now has been in a single window. In this chapter, we'll cover how to 
use multiple windows, changing various attributes of windows, and use some of the standard dialog 
box windows that are available in Tk. 
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Creating and Destroying Windows 


You've already seen that all Tk programs start out with a root toplevel window, and then widgets are 
created as children of that root window. Creating new toplevel windows works almost exactly the 
same as creating new widgets. 


Toplevel windows are created using the Toplevel function: 


t = Toplevel(parent) 


Unlike regular widgets, you don't have to "grid" a toplevel for it to appear onscreen. Once you've 
created a new toplevel, you can then create other widgets which are children of that toplevel, and 
grid them inside the toplevel. In other words, the new toplevel behaves exactly like the 
automatically created root window. 


To destroy a window, you can use the destroy method on a widget: 


window.destroy() 


Note that you can use destroy on any widget, not just a toplevel window. Also, when you destroy 
a window, all windows (widgets) that are children of that window are also destroyed. So if you 
happen to destroy the root window (that all other widgets are descended from), that will normally 
end your application. 


Changing Window Behavior and Styles 


There are lots of things about how windows behave and how they look that can be changed. 


Window Title 
To examine or change the title of the window: 


oldtitle = window.title() 
window.title('New title') 


Size and Location 
In Tk, a window's position and size on the screen is known as its geometry. A full geometry 


specification looks like this: 


widthxheightixty 


Width and height (normally in pixels) are pretty self-explanatory. The "x" (horizontal position) is 
specified with a leading plus or minus, so "+25" means the left edge of the window should be 25 
pixels from the left edge of the screen, while '-50" means the right edge of the window should be 
50 pixels from the right edge of the screen. Similarly, a "y" (vertical) position of "+10" means the 
top edge of the window should be ten pixels below the top of the screen, while "-100" means the 
bottom edge of the window should be 100 pixels above the bottom of the screen. 
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Remember that the geometry's position are the actual coordinates on the screen, and don't make 
allowances for systems like Mac OS X which have a menubar along the top, or a dock area along 
the bottom. So specifying a position of "+0+0" would actually place the top part of the window 
under the system menu bar. It's a good idea to leave a healthy margin (at least 30 pixels) from an 
edge of the screen. 


Here is an example of changing the size and position, placing the window towards the top righthand 
corner of the screen: 


window.geometry('300x200-5+40' ) 


Stacking Order 


Stacking order refers to the order that windows are "placed" on the screen, from bottom to top. 
When the positions of two windows overlap each other, the one closer to the top of the stacking 
order will obscure or overlap the one lower in the stacking order. 


You can obtain the current stacking order, a list from lowest to heighest, via: 


root.tk.eval('wm stackorder '+str(window) ) 


This method doesn't appear to be exposed cleanly through Tkinter's API. 


You can also just check if one window is above or below another: 


if (root.tk.eval('wm stackorder '+str(window)+' isabove 
‘+str(otherwindow))==" 1. di 

if (root.tk.eval('wm stackorder '+str(window)+' isbelow 
'+str(otherwindow) )=='1' ) 


You can also raise or lower windows, either to the very top (bottom) of the stacking order, or just 
above (below) a designated window: 


window. 1lift() 
window. 1lift(otherwin) 
window. lower () 
window. lower (otherwin) 


Tkinter uses the name ‘lift’, since 'raise' is a reserved keyword. 


Wondering why you needed to pass a window to get the current stacking order? It turns out that 
stacking order, raise and lower, etc. work not only for toplevel windows, but with any "sibling" 
widgets (those having the same parent). So if you have several widgets gridded together but 
overlapping, you can raise and lower them relative to each other. For example: 


from tkinter import * 

from tkinter import ttk 

root = Tk() 

little = ttk.Label(root, text="Little") 

bigger = ttk.Label(root, text='Much bigger label') 
little.grid(column=0, row=0) 

bigger .grid(column=0, row=0) 

root.after(2000, lambda: little.lift()) 

root .mainloop( ) 
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The "after" command schedules a script to be executed at a certain number of milliseconds in 
the future, but allows normal processing of the event loop to continue in the meantime. 


Resizing Behavior 

Normally, toplevel windows, both the root window and others that you create, can be resized by the 
user. However, sometimes in your user interface, you may want to prevent the user from resizing 
the window. You can prevent it from being resized, in fact independently specifying whether the 
window's width (first parameter) can be changed, as well as its height (second parameter). So to 
disable all resizing: 


window.resizable( FALSE, FALSE) 


Remember that if you've added a ttk: :Sizegrip widget to the window, that you should remove 
it if you're making the window non-resizable. 


If resizing is enabled, you can specify a minimum and/or maximum size that you'd like the 
window's size to be constrained to (again, parameters are width and height): 


window.minsize(200, 100) 
window.maxsize(500, 500) 


Iconifying and Withdrawing 

On most systems, you can temporarily remove the window from the screen by iconifying it. In Tk, 
whether or not a window is iconified is referred to as the window's state. The possible states for a 

window include "normal" and "iconic" (for an iconified window), as well as several others: 
"withdrawn", "icon" or "zoomed". 


You can query or set the current window state, and there are also the methods "iconify" and 
"deiconify" which are shortcuts for setting the "iconic" or "normal" states respectively. 


thestate = window.state() 
window.state('normal' ) 
window. iconify() 

window. deiconify() 


Standard Dialogs 


Dialog boxes are a type of window used in applications to get some information from the user, 
inform them that some event has occurred, confirm an action and more. The appearance and usage 
of dialog boxes is usually quite specifically detailed in a platform's style guide. Tk comes with a 
number of dialog boxes built-in for common tasks, and which help you conform to platform specific 
style guidelines. 


Selecting Files and Directories 


Tk provides several dialogs to let the user select files or directories. On Windows and Mac, these 
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invoke the underlying operating system dialogs directly. The "open" variant on the dialog is used 
when you want the user to select an existing file (like in a "File | Open..." menu command), while 
the "save" variant is used to choose a file to save into (normally used by the "File | Save As...” menu 


command). 


from tkinter import filedialog 
filename = filedialog.askopenfilename() 

filename = filedialog.asksaveasfilename() 
dirname = filedialog.askdirectory() 


All of these commands produce modal dialogs, which means that the commands (and hence your 
program) will not continue running until the user submits the dialog. The commands return the full 
pathname of the file or directory the user has chosen, or return an empty string if the user cancels 


out of the dialog. 
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There are a variety of different options that can be passed to these dialogs, allowing you to set the 
allowable file types, default filename, and more. These are detailed in the getOpenFile/getSaveFile 
and chooseDirectory reference manual pages. 


Selecting Colors 


There is also a modal dialog to let the user select a color. It will return a color value, e.g. "#ff62b8". 
The dialog takes an optional "initialcolor" option to specify an existing color that the user is 


presumably replacing. 


from tkinter import colorchooser 
colorchooser.askcolor(initialcolor='#ff0000' ) 
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One thing missing in Tk 8.5 is a font chooser dialog. That has actually been added in Tk 8.6. 


Alert and Confirmation Dialogs 


Many applications use various simple modal alerts or dialogs to notify the user of an event, ask 
them to confirm an action, or make another similar choice which is done by clicking on a button. Tk 
provides a versatile "message box" that encapsulates all these different types of dialogs. 


from tkinter import messagebox 
messagebox.showinfo(message='Have a good day') 


Q Have a good day 


Mac OS X Windows 


Simple Message Boxes 


messagebox .askyesno( 


message='Are you sure you want to install SuperVirus?' 


icon='question' title='Install') 


Install 


Are you sure you want to install 
SuperVirus? 


© install 


Mac OS X Windows 


Example Message Boxes 


e Are you sure you went to install SuperVirus? 
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Like the previous dialogs that we've seen, these are modal, and will return the result of the user's 
action to the caller. The exact return value will depend on the "type" option passed to the 


command, as shown here: 


Type option Possible return values 
ok (default) "ok" 
okcancel "ok" or "cancel" 
yesno "yes" or "no" 
yesnocancel "yes", "no" or "cancel" 
retrycancel "retry" or "cancel" 
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abortretryignore "abort", "retry" or "ignore" 

Rather than using a 'type' option, Tkinter uses a different method name for each type of dialog. The 
available methods are: askokcancel, askquestion, askretrycancel, askyesno, askyesnocancel, 
showerror, showinfo, showwarning. 


The full list of possible options is shown here: 
type As described above. 


message The main message displayed inside the alert. 


If needed, a secondary message, often displayed in a smaller font under the main 


detail 
message. 
title Title for the dialog window. Not used on Mac OS X. 
icon Icon to show: one of "info" (default), "error", "question" or "warning". 


Specify which button (e.g. "ok" or "cancel" fora "okcancel" type dialog) 

should be the default. 

parent Specify a window of your application this dialog is being posted for; this may cause 
the dialog to appear on top, or on Mac OS X appear as a sheet for the window. 

These new messagebox dialogs are a replacement from the older "tk_dialog'" command, which 


default 


does not comply with current platform user interface conventions. 


Organizing Complex Interfaces 


If you have a large user interface, you'll need to find ways to organize it in ways that don't 
overwhelm your users with the complexity. There are a number of different approaches to doing 
this; again, both general and platform specific human interface guidelines are a good resource when 
deciding. 

Note that when we're talking about complexity in this chapter, it's not the underlying technical 
complexity of how the program is put together, but how it's presented to the user. A user interface 


can be pulled together from many different modules, be built up from multiple canvas widgets and 
deeply nested frames, but that doesn't necessarily mean the user perceives it to be complex. 


Multiple windows 

One of the benefits of using multiple windows in an application can be to simplify the user 
interface, by requiring the user to focus only on the contents of one window at a time (requiring 
them to focus on or switch between several windows can also have the opposite effect). Similarly, 
showing only the widgets that are relevant for the current task (via grid) can help simplify the user 
interface. 


White space 


If you do need to display a large number of widgets onscreen at the same time, you have to think 
about how to organize them visually. You've seen how gr id can help by making it easy to align 
widgets with each other. White space is another useful aid. Placing related widgets quite close to 
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each other (possible with an explanatory label immediately above) and separated from other less- 
related widgets by white space helps the user organize the user interface in their own mind. 


The amount of white space around different widgets, between groups of widgets, around borders 
and so on is highly platform specific. While you can do an adequate job without worrying about 
exact pixel numbers, if you want a highly polished user interface, you'll need to tune this for each 
platform. 


Separator 


e Widget Roundup 
e Reference Manual 


A second approach to grouping widgets in one display is to place a thin horizontal or vertical rule 
between groups of widgets; often this can be more space efficient than using white space, which 
may be relevant for a tight display. Tk provides a very simple separator widget for this purpose. 


MIA 


Mac OS X Windows Linux 


Separator Widgets 
Separators are created using the ttk.Separator function: 


s = ttk.Separator(parent, orient=HORIZONTAL) 


The "orient" option may be specified as either "horizontal" or "vertical". 


Label Frames 


e Widget Roundup 
e Reference Manual 


A labelframe widget, also commonly known as a group box, provides another way to group related 
components. It acts like a normal ttk: : frame, in that you will normally use it as a container for 
other widgets you gr 1d inside it. However, it displays in a way that visually sets it off from the rest 
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of the user interface. You can optionally provide a text label to be displayed outside the labelframe. 


Nuclear Plant: 
Nuclear Plant: -Nuclear Plant: 


Mac OS X Windows Linux 
Labelframe Widgets 
Labelframes are created using the ttk. Labelframe function: 


lf = ttk.Labelframe(parent, text='Label' ) 


Paned Windows 


e Widget Roundup 
e Reference Manual 


A panedwindow widget lets you stack two or more resizable widgets above and below each other 
(or to the left and right). The user can adjust the relative heights (or widths) of each pane by 
dragging a sash located between them. Typically the widgets you're adding to a panedwindow will 
be frames containing many other widgets. 


Pane Pane Pane3 Panel Pane2 Pane3 Panel Pane2 Pane3 


Mac OS X Windows Linux 


Panedwindow Widgets (Shown here managing several labelframes) 
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Panedwindows are created using the ttk . Panedwindow function: 


p = ttk.Panedwindow(parent, orient=VERTICAL) 

# first pane, which would get widgets gridded into it: 

f1 = ttk.Labelframe(p, text='Pane1', width=100, height=100) 

f2 = ttk.Labelframe(p, text='Pane2', width=100, height=100) # second pane 
p.add(f1) 

p.add(f2) 


A panedwindow is either "vertical" (it's panes are stacked vertically on top of each other), or 
"horizontal". Importantly, all of the panes that you add to the panedwindow must be a direct 
child of the panedwindow itself. 


Calling the "add" method will add a new pane at the end of the list of panes. The "insert 
position subwindow" method allows you to place the pane at the given position in the list of 
panes (0..n-1); if the pane is already managed by the panedwindow, it will be moved to the new 
position. You can use the "forget subwindow" to remove a pane from the panedwindow; you 
can also pass a position instead of a subwindow. 


Other options let you sign relative weights to each pane so that if the overall panedwindow resizes, 
certain panes will get more space than others. As well, you can adjust the position of each sash 
between items in the panedwindow. See the command reference for details. 


Notebook 


e Widget Roundup 
e Reference Manual 


A notebook widget uses the metaphor of a tabbed notebook to let the user switch between one of 
several pages, using an index tab. In this case, unlike with paned windows, we're only allowing the 
user to look at a single page (akin to a pane) at a time. 


|One| Two [Three One Two | | 


Mac OS X Windows Linux 
Notebook Widgets 


Notebooks are created using the ttk .Notebook function: 


= ttk.Notebook(parent) 
ttk.Frame(n) # first page, which would get widgets gridded into it 


n 
f1 
f2 ttk.Frame(n) # second page 
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n.add(f1, text='One') 
n.add(f2, text='Two') 


The operations on tabbed notebooks are similar to those on panedwindows. Each page is typically a 
frame, again a direct child (subwindow) of the notebook itself. A new page and its associated tab are 
added to the end of the list of tabs with the "add subwindow ?option value...?" 
method. The "text" tab option is used to set the label on the tab; also useful is the "state" tab 
option, which can have the value "normal", "disabled" (not selectable), or "hidden". 


To insert a tab at somewhere other than the end of the list, you can use the "insert position 
subwindow ?option value...?", and to remove a given tab, use the "forget" method, 
passing it either the position (0..n-1) or the tab's subwindow. You can retrieve the list of all 
subwindows contained in the notebook via the "tabs" method. 


To retrieve the subwindow that is currently selected, call the "Select" method, and change the 
selected tab by passing it either the tab's position or the subwindow itself as a parameter. 


To change a tab option (like the text label on the tab or its state), you can use the "tab (tabid, 
option=value" method (where "tabid" is again the tab's position or subwindow); omit the 
"=value" to return the current value of the option. 


Again, there are a variety of less frequently used options and commands detailed in the command 
reference. 


Fonts, Colors, Images 


This chapter describes how Tk handles fonts, colors and images. We've touched on all of these 
before, but here we'll provide a more in depth treatment. 


Fonts 


Several Tk widgets, such as the label, text, and canvas, allow you to specify the fonts used to 
display text, typically via a "font" configuration option. As with many things in Tk, the default 
fonts are usually a good choice, but if you do want to make changes, this section will describe 
several ways to do so. Fonts are one of several areas that are highly platform specific, so how you 
specify them is important. 


The font command reference provides full details on specifying fonts, as well as other font-related 
operations. 


Most of the themed widgets that display text don't have a "font" configuration option, unlike the 
classic Tk widgets. Rather than modifying individual widgets, the correct approach in the themed 
widgets is to specify the fonts used in a style, and then use that style for the individual widget. This 
is akin to the difference between hardcoding display-oriented markup like font tags inside HTML 
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pages, vs. using CSS stylesheets that keep all the display specific information in one place. 


Many older Tk programs hardcoded a lot of fonts, using either the "family size style" format we'll 
see below, X11 font names, or the older and more arcane X11 font specification string. In many 
cases, this left these applications with a dated look as platforms evolved. Further, many programs 
specified fonts on a per-widget basis, leaving the font decisions spread out through the program. 
Named fonts, and use of the standard fonts that Tk provides, are a far better solution. Reviewing 
and updating the usage of fonts is an easy and important change to make in any existing 
applications. 


Standard Fonts 


Particularly for more-or-less standard user interface elements, each platform defines specific fonts 
that should be used. Tk encapsulates many of these into a standard set of fonts that are always 
available, and of course the standard widgets use these fonts. This helps abstract away platform 
differences. The predefined fonts are: 


TkDefaultFont The default for all GUI items not otherwise specified. 
TkTextFont Used for entry widgets, listboxes, etc. 

TkFixedFont A standard fixed-width font. 

TkMenuFont The font used for menu items. 

TkHeadingFont The font typically used for column headings in lists and tables. 
TkCaptionFont A font for window and dialog caption bars. 
TkSmallCaptionFont A smaller caption font for subwindows or tool dialogs 
TkIconFont A font for icon captions. 

TkTooltipFont A font for tooltips. 


Platform-Specific Fonts 
A number of additional predefined fonts are available, but the precise set depends on the platform. 


Obviously, if you're using these, and your application is portable across different platforms, you'll 
need to ensure that proper fonts are defined individually for each platform. 


On X11, any valid X11 font name (see e.g. the "xlsfonts" command) may be used. Remember 
though that there is no guarantee that a particular font has been installed on a particular machine. 


On Windows, the following font names, which map to the fonts that can be set in the "Display" 
Control Panel, are available: system, ansi, device, systemfixed, ansifixed, 
oemfixed. 


On Mac OS X, the following fonts are available (see the Apple HIG for details): 
systemSystemFont, systemSmallSystemFont, systemApplicationFont, 
systemViewsFont, systemMenuItemFont, systemMenuItemCmdKeyFont, 
systemPushButtonFont, systemAlertHeaderFont, systemMiniSystemFont, 
systemDetailEmphasizedSystemFont, systemEmphasizedSystemFont, 
systemSmallEmphasizedSystemFont, systemLabelFont, 


79 


systemMenuTitleFont, systemMenuItemMarkFont, systemWindowTitleFont, 
systemUtilityWindowTitleFont, systemToolbarFont, 
systemDetailSystemFont. 


If you'd like to examine what actual font is being assigned to any of the standard or default fonts (or 
any font for that matter), you can use the "font actual" call. 


Named Fonts 

You can also create your own fonts, which can be used exactly like the predefined ones. To do so, 
you'll need to pick a name to refer to the font, and then specify various font attributes that define 
how the font should look. Typically, you'd use different font attributes on different platforms; that 
way, you can use the font in your program without worrying about the details except in the one 
place the font is actually defined. 


Here's an example: 


from tkinter import font 
appHighlightFont = font.Font(family='Helvetica', size=12, weight='bold') 
ttk.Label(root, text='Attention!', font=appHighlightFont).grid() 


The "family" specifies the font name; the names Courier, Times, and Helvetica are 
guaranteed to be supported (and mapped to an appropriate monospaced, serif, or sans-serif font), 
but other fonts installed on the system can be used (again, be careful to ensure the font exists, or the 
system will supply a different font, which may not necessarily be a good match). You can get the 
names of all available fonts with: 


font .families() 


The "size" option specifies the size of the font, in points. The "weight" option can be either 
bold or normal. You can specify a "Slant" of roman (normal) or italic. Finally, the 
boolean options "underline" and "overstrike" are available. 


The current settings of these options can be examined or changed using the same mechanisms that 
you'd use for changing the configuration options of a widget (e.g. configure). 


Font Descriptions 


Another way to specify fonts is via a list of attributes, starting with the name of the font, and then 
optionally including a size, and optionally one or more style options. Some examples of this are 
"Helvetica", "Helvetica 12", "Helvetica 12 bold", and "Helvetica 12 bold 
italic". These font descriptions are then used as the value of the "font" configuration option, 
rather than a predefined or named font. 


In general, switching from font descriptions to named fonts is advisable, again to isolate font 
differences in one location in the program. 
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Colors 


As with fonts, there are various ways to specify colors. Full details can be found in the colors 
command reference. 


In general, the system will provide the right colors for most things. Like with fonts, both Mac and 
Windows specify a large number of system-specific color names (see the reference), whose actual 
color may depend upon system settings (e.g. text highlight colors, default backgrounds). 


You can also specify colors via RGB, like in HTML, e.g. "#3FF" or "#FFO16A". Finally, Tk 
recognizes the set of color names defined by X11; normally these are not used, except for very 
common ones such as "red", "black", etc. 


For themed Tk widgets, colors are often used in defining styles that are applied to widgets, rather 
than applying the color to a widget directly. 


It probably goes without saying that restraint in the use of colors is normally warranted. 


Images 


We've seen the basics of how to use images already, displaying them in labels or buttons for 
example. We create an image object, usually from a file on disk. 


imgobj = PhotoImage(file='myimage.gif') 
label['image'] = imgobj 


Out of the box, Tk includes support for GIF and PPM/PNM images. However, there is a Tk 
extension library called "Img" which adds support for many others: BMP, XBM, XPM, PNG, 
JPEG, TIFF, etc. Though not included directly in the Tk core, Img is usually included with other 
packaged distributions (e.g. ActiveTcl). 


Instead of using Tk's Img extension, Tkinter uses a made-for-Python image library called 'PIL' 
(Python Imaging Library). More specifically, we'll use a more up-to-date fork of PIL called ‘pillow’. 
As it doesn't come bundled with Python, you'll normally need to install it. You should be able to do 
so via, e.g. 'pip install Pillow’. 


from PIL import ImageTk, Image 
myimg = ImageTk.PhotoImage(Image.open( 'myimage.png' ) ) 


The 'ImageTk.PhotoImage' call provides a drop-in replacement for Tk's PhotoImage, but supports 
the broader range of image types. 


Tk's images are actually quite powerful and sophisticated, and provide a wide variety of ways to 
inspect and modify images. You can find out more from the image command reference and the 


photo command reference. 


The types of multi-color images we've seen here are referred to in Tk as photo images. Tk also 
provides a second type of images, two-bit bitmap images, which were widely used in the 90's when 
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most Unix workstations used quite large (compared with PCs) monitors, but they were only black 
and white. Needless to say, color is de rigueur these days, so updating to full color images for icons 
and so on is highly advisable. 


Problems with PIL/Pillow on Mac OS X? 


If you're running on Mac OS X, did you get a crash using PIL/Pillow? Are you maybe seeing error 
messages in your Terminal saying things like: 


Class TKApplication is implemented in both 
/Library/Frameworks/Tk.framework/Versions/8.5/Tk and 
/System/Library/Frameworks/Tk.framework/Versions/8.5/Tk. 
One of the two will be used. Which one is undefined. 


This can occur when you download a binary of an extension which is linked against a different 
versions of Tcl and Tk than you're running. In this case, you're running the ActiveTcl one in 
/Library/Frameworks, and the extension is trying to link against the one provided by Mac OS X 
in /System/Library/Frameworks. 


This is one of the difficulties with binary extensions. The snippet below shows how we might fix 
this problem. It's specific to the version of the Pillow extension that we happened to have installed, 
but hopefully it can guide you in terms of locating and fixing the binaries for any extension causing 
problems for you. The steps are roughly: find the binary, verify it is linking against the wrong 
version (via OtOO1), and change what its linking against, using a program called 
install_name_tool. 


% cd /Library/Frameworks/Python.framework/Versions/3.4 

% find . -name '_imagingtk.so' 

./1ib/python3.4/site-packages/PIL/_imagingtk.so 

% cd 1lib/python3.4/site-packages/PIL 

% otool -L _imagingtk.so 

_imagingtk.so: 
/System/Library/Frameworks/Tcl.framework/Versions/8.5/Tcl (...) 
/System/Library/Frameworks/Tk.framework/Versions/8.5/Tk (...) 
/usr/lib/libSystem.B.dylib (...) 

% install_name_tool -change 

/System/Library/Frameworks/Tcl.framework/Versions/8.5/Tcl 
/Library/Frameworks/Tcl.framework/Versions/8.5/Tc1 _imagingtk.so 

% install_name_tool -change 

/System/Library/Frameworks/Tk. framework/Versions/8.5/Tk 
/Library/Frameworks/Tk.framework/Versions/8.5/Tk _imagingtk.so 

% otool -L _imagingtk.so 

_imagingtk.so: 
/Library/Frameworks/Tcl1.framework/Versions/8.5/Tc1 (...) 
/Library/Frameworks/Tk.framework/Versions/8.5/Tk (...) 
/usr/lib/libSystem.B.dylib (...) 


Canvas 


e Widget Roundu 
e Reference Manual 
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A canvas widget manages a 2D collection of graphical objects — lines, circles, images, other 
widgets and more. Tk's canvas is an incredibly powerful and flexible widget, and truly one of Tk's 
highlights. It is suitable for a wide range of uses, including drawing or diagramming, CAD tools, 
displaying or monitoring simulations or actual equipment, and for building more complex widgets 
out of simpler ones. Canvas widgets are part of the classic Tk widgets, not the themed Tk widgets. 


Mac OS X Windows Linux 
Canvas Widgets 
Canvas widgets are created using the Canvas function: 


canvas = Canvas(parent) 


Because canvas widgets have a huge amount of features, we won't be able to cover everything here. 
What we will do is take a fairly simple example (a freehand sketching tool) and incrementally add 
new pieces to it, each showing another new feature of canvas widgets. Towards the end of the 
chapter, we'll then cover some of the other major features not illustrated in the example. 


Creating Items 


When you create a new canvas widget, it will essentially be a large rectangle with nothing on it; 
truly a blank canvas in other words. To do anything useful with it, you'll need to add items to it. As 
mentioned, there are a wide variety of different types of items you can add. Here, we'll look at 
adding a simple line item to the canvas. 


To create a line, the one piece of information you'll need to specify is where the line should be. This 
is done by using the coordinates of the starting and ending point, expressed as a list of the form xO 
yO x1 y1.The origin (0,0) is at the top left corner of the canvas, with the x value increasing as 
you move to the right, and the y value increasing as you move down. So to create a line from 
(10,10) to (200,50), we'd use this code: 


canvas.create_line(10, 10, 200, 50) 


The "create_line" method will return an item id (an integer) that can be used to uniquely refer 
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to this item; every item created will get its own id. Though often we don't need to refer to the item 
later and will therefore ignore the returned id, we'll see how it can be used shortly. 


Let's start our simple sketchpad example. For now, we'll want to be able to draw freehand on the 
canvas by dragging the mouse on it. We'll create a canvas widget, and then attach event bindings to 
it to capture mouse clicks and drags. When we first click the mouse, we'll remember that location as 
our "start" position. Every time the mouse is moved with the mouse button still held down, we'll 
create a line item going from this "start" position to the current mouse position. The current position 
will then be the "start" position for the next line segment. 


from tkinter import * 
from tkinter import ttk 


lastx, lasty = 0, 0 


def xy(event): 
global lastx, lasty 
lastx, lasty = event.x, event.y 


def addLine(event): 
global lastx, lasty 
canvas.create_line((lastx, lasty, event.x, event.y)) 
lastx, lasty = event.x, event.y 


root = Tk() 

root.columnconfigure(0, weight=1) 
root.rowconfigure(0, weight=1) 

canvas = Canvas(root) 

canvas.grid(column=0, row=0, sticky=(N, W, E, S)) 
canvas.bind("<Button-1>", xy) 
canvas.bind("<B1-Motion>", addLine) 


root .mainloop() 


Try it out - drag the mouse around the canvas to create your masterpiece. 


Item Attributes 


When creating items, you can also specify one or more attributes for the item, that will affect how it 
is displayed. For example, here we'll specify that the line should be red, and three pixels wide. 


canvas.create_line(10, 10, 200, 50, fill='red', width=3) 
The exact set of attributes will vary according to the type of item. 


Like with Tk widgets, changing attributes for canvas items after you've already created them can 
also be done. 


id = canvas.create_line(0, 0, 10, 10, fill='red') 


canvas.itemconfigure(id, fill='blue', width=2) 


84 


Bindings 
We've already seen that the canvas widget as a whole, like any other Tk widget, can capture events 
using the "bind" command. 


You can also attach bindings to individual items in the canvas (or groups of them, as we'll see in the 
next section using tags). So if you want to know whether or not a particular item has been clicked 
on, you don't need to watch for mouse click events for the canvas as a whole, and then figure out if 
that click happened on your item. Tk will take care of all this for you. 


To capture these events, you use a bind command built into the canvas. It works exactly like the 
regular bind command, taking an event pattern and a callback. The only difference is you specify 
the canvas item this binding applies to. 


canvas.tag_bind(id, '<1>', ...) 


Note the difference between the item-specific "tag_bind" method, and the widgetlevel "bind" 
method. 


Let's add some code to our sketchpad example to allow changing the drawing color. We'll first 
create a few different rectangle items, each filled with a different color. Creating rectangle items is 
just like creating line items, where you'll specify the coordinates of two diagonally opposite corners. 
We'll then attach a binding to each of these so that when they're clicked on, they'll set a global 
variable to the color to use. Our mouse motion binding will look at that variable when creating the 
line segments. 

color = "black" 

def setColor(newcolor): 


global color 
color = newcolor 


def addLine(event): 
global lastx, lasty 
canvas.create_line((lastx, lasty, event.x, event.y), fill=color) 
lastx, lasty = event.x, event.y 


id = canvas.create_rectangle((10, 10, 30, 30), fill="red") 
canvas.tag_bind(id, "<Button-1>", lambda x: setColor("red")) 
id = canvas.create_rectangle((10, 35, 30, 55), fill="blue") 
canvas.tag_bind(id, "<Button-1>", lambda x: setColor("blue") ) 
id = canvas.create_rectangle((10, 60, 30, 80), fill="black") 
canvas.tag_bind(id, "<Button-1>", lambda x: setColor("black")) 


Tags 
We've seen that every canvas item has a unique id number, but there is another very useful and 
powerful way to refer to items on a canvas, and that is using tags. 
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A tag is just an identifier of your creation, something meaningful to your program. You can attach 
tags to canvas items; each item can have any number of tags. Unlike item id numbers, which are 
unique for each item, many items can have the same tag. 


What can you do with tags? We saw that you can use the item id to modify a canvas item (and we'll 
see soon there are other things you can do to items, like move them around, delete them, etc.). Any 
time you can use an item id, you can use a tag. So for example, you can change the color of all 
items having a specific tag. 


Tags are a good way to identify certain types of items in your canvas (items that are part of a drawn 
line, items that are part of the pallette, etc.). You can use tags to correlate canvas items to particular 
objects in your application (so for example, tag all canvas items that are part of the robot with id 
#37 with the tag "robot37"). With tags, you don't have to keep track of the ids of canvas items to 
refer to groups of items later; tags let Tk do that for you. 


You can assign tags when creating an item using the "tags" item configuration option. You can 
add tags later with the "addtag" method, or remove them with the "dtags" method. You can 
get the list of tags for an item with the "gettags” method, or return a list of item id numbers 
having the given tag with the "find" command. 


For example: 


>>> c = Canvas(root) 

>>> c.create_line(10, 10, 20, 20, tags=('firstline', 'drawing')) 
1 

>>> c.create_rectangle(30, 30, 40, 40, tags=('drawing')) 
2 

>>> c.addtag('rectangle', 'withtag', 2) 

>>> c.addtag('polygon', 'withtag', 'rectangle') 

>>> c.gettags(2) 

('drawing', 'rectangle', 'polygon') 

>>> c.dtag(2, 'polygon') 

>>> c.gettags(2) 


('drawing', 'rectangle') 
>>> c.find_withtag('drawing' ) 
(1, 2) 


As you can see, things like "withtag" will take either an individual item or a tag; in the latter 
case, they will apply to all items having that tag (which could be none). The "addtag" and 
"find" have many other options, allowing you to specify items near a point, overlapping a 
particular area, and more. 


Let's use tags first to put a border around whichever item in our color palette is currently selected. 


def setColor(newcolor): 
global color 
color = newcolor 
canvas.dtag('all', 'paletteSelected') 
canvas.itemconfigure('palette', outline='white' ) 
canvas.addtag('paletteSelected', 'withtag', 'palette%s' % color) 
canvas.itemconfigure('paletteSelected', outline='#999999' ) 


id = canvas.create_rectangle((10, 10, 30, 30), fill="red", tags=('palette', 
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'palettered')) 

id = canvas.create_rectangle((10, 35, 30, 55), fill="blue", tags=('palette', 
'paletteblue')) 

id = canvas.create_rectangle((10, 60, 30, 80), fill="black", tags=('palette', 
'paletteblack', 'paletteSelected')) 


setColor('black' ) 
canvas.itemconfigure('palette', width=5) 


Let's also use tags to make the current stroke we're drawing appear more visible; when we release 
the mouse we'll put it back to normal. 


def addLine(event): 

global lastx, lasty 

canvas.create_line((lastx, lasty, event.x, event.y), fill=color, width=5, 
tags='currentline' ) 

lastx, lasty = event.x, event.y 


def doneStroke(event): 
canvas.itemconfigure('currentline', width=1) 


canvas.bind("<B1-ButtonRelease>", doneStroke) 


Modifying Items 
You've seen how you can modify the configuration options on an item — its color, width and so on. 
There are a number of other things you can do items. 


To delete items, use the "delete" method. To change an item's size and position, you can use the 
"coords" method; this allows you to provide new coordinates for the item, specified the same 
way as when you first created the item. Calling this method without a new set of coordinates will 
return the current coordinates of the item. To move one or more items by a particular horizontal or 
vertical amount from their current location, you can use the "move" method. 


All items are ordered from top to bottom in what's called the stacking order. If an item later in the 
stacking order overlaps the coordinates of an item below it, the item on top will be drawn on top of 
the lower item. The "raise" and "lower" methods allow you to adjust an item's position in the 
stacking order. 


There are several more operations described in the reference manual page, both to modify items and 
to retrieve additional information about them. 


Scrolling 


In many applications, you'll want the canvas to be larger than what appears on the screen. You can 
attach horizontal and vertical scrollbars to the canvas in the usual way, via the "Xview" and 
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"yview' methods. 


As far as the size of the canvas, you can specify both how large you'd like it to be on screen, as well 
as what the full size of the canvas is, which would require scrolling to see. The "width" and 
"height" configuration options for the canvas widget will request the given amount of space 
from the geometry manager. The "scrollregion" configuration option (e.g. "0 © 1000 
1000") tells Tk how large the canvas surface is. 


You should be able to modify the sketchpad program to add scrolling, given what you already know. 
Give it a try. 


Once you've done that, scroll the canvas down just a little bit, and then try drawing. You'll see that 
the line you're drawing appears above where the mouse is pointing! Surprised? 


What's going on is that the global "bind" command doesn't know that the canvas is scrolled (it 
doesn't know the details of any particular widget). So if you've scrolled the canvas down by 50 
pixels, and you click on the top left corner, bind will report that you've clicked at (0,0). But we 
know that because of the scrolling, that position should really be (0,50). 


The "canvasx" and "canvasy" methods will translate the position onscreen (which bind is 
reporting) into the actual point on the canvas, taking into account scrolling. If you're adding these 
directly to the event bindings (as opposed to procedures called from the event bindings), be careful 
about quoting and substitutions, to make sure that the conversions are done when the event fires. 


Here then is our complete example. We probably don't want the palette to be scrolled away when 
the canvas is scrolled, but we'll leave that for another day. 


from tkinter import * 
from tkinter import ttk 
root = Tk() 


h = ttk.Scrollbar(root, orient=HORIZONTAL) 

v = ttk.Scrollbar(root, orient=VERTICAL) 

canvas = Canvas(root, scrollregion=(0, 0, 1000, 1000), yscrollcommand=v.set, 
xscrollcommand=h.set) 

h['command'] = canvas.xview 

v['command'] = canvas.yview 

ttk.Sizegrip(root).grid(column=1, row=1, sticky=(S,E)) 


canvas .grid(column=0, row=0, sticky=(N,W,E,S)) 
h.grid(column=0, row=1, sticky=(W,E)) 
v.grid(column=1, row=0, sticky=(N,S)) 
root.grid_columnconfigure(0, weight=1) 
root.grid_rowconfigure(0, weight=1) 


lastx, lasty = 0, O 
def xy(event): 

global lastx, lasty 

lastx, lasty = canvas.canvasx(event.x), canvas.canvasy(event.y) 
def setColor(newcolor): 


global color 
color = newcolor 
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canvas.dtag('all', 'paletteSelected') 
canvas.itemconfigure('palette', outline='white' ) 
canvas.addtag('paletteSelected', 'withtag', 'palette%s' % color) 
canvas.itemconfigure('paletteSelected', outline='#999999' ) 


def addLine(event): 
global lastx, lasty 
X, y = canvas.canvasx(event.x), canvas.canvasy(event.y) 
canvas.create_line((lastx, lasty, x, y), fill=color, width=5, 
tags='currentline' ) 
lastx, lasty = x, y 


def doneStroke(event): 
canvas.itemconfigure('currentline', width=1) 


canvas.bind("<Button-1>", xy) 
canvas.bind("<B1-Motion>", addLine) 
canvas.bind("<B1-ButtonRelease>", doneStroke) 


id = canvas.create_rectangle((10, 10, 30, 30), fill="red", tags=('palette', 
'palettered')) 

canvas.tag_bind(id, "<Button-1>", lambda x: setColor("red")) 

id = canvas.create_rectangle((10, 35, 30, 55), fill="blue", tags=('palette', 
'paletteblue')) 

canvas.tag_bind(id, "<Button-1>", lambda x: setColor("blue") ) 

id = canvas.create_rectangle((10, 60, 30, 80), fill="black", tags=('palette', 
'paletteblack', 'paletteSelected')) 

canvas.tag_bind(id, "<Button-1>", lambda x: setColor("black")) 


setColor('black' ) 
canvas.itemconfigure('palette', width=5) 
root .mainloop() 


Other Item Types 
Besides lines and rectangles, there are a number of different types of items that canvas widgets 


support. Remember that each one has its own set of item configuration options, detailed in the 
reference manual. 


Items of type "line" can actually be a bit fancier than what we've seen. A line item can actually 
be a series of line segments, not just one; in our example, we could have chosen to use a single line 
item for each complete stroke. The line can also be drawn directly point-to-point, or smoothed out 
into a curved line. 


Items of type "rectangle" we've seen. Items of type "Oval" work the same but draw as an 
oval. Items of type "arc" allow you to draw just a piece of an oval. Items of type "polygon" 
allow you to draw a closed polygon with any number of sides. 


Pictures can be added to canvas widgets, using items of type "bitmap" (for black and white), or 
type "image" (for full color). 


You can add text to a canvas using items of type "text". You have complete control of the font, 
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size, color and more, as well as the actual text that is displayed. 


Perhaps most interestingly, you can embed other widgets (which would include a frame which itself 
contains other widgets) into a canvas using an item of type "window". When we do this, the 
canvas in effect acts as a geometry manager for those other widgets. This capability raises all kinds 
of possibilities for your application. 


There is a lot more to canvas widgets than we've described here; be sure to consult the reference 
manual, as well as the wide range of example programs included with the Tk distribution. 


Text 


e Widget Roundup 
e Reference Manual 


A text widget manages a multi-line text area. Like the canvas widget, Tk's text widget is an 
immensely flexible and powerful tool which can be used for a wide variety of tasks. Some example 
uses of text widgets have included anything from providing a simple multi-line text area as part of a 
form, to a stylized code editor, to an outliner, to a web browser. Text widgets are part of the classic 
Tk widgets, not the themed Tk widgets. 


Lorem ipsum dolor Lorem HE Lorem ipsum dolor 
sit amet, donec a CAS, donec a sit amet, donec a 
dignissimos orci dignissimos orci dignissimos orci 
non, nonummy non, nonummy non, nonummy 
tristique sit tristique sit tristique sit 
metus, velit odio metus, velit odio metus, velit odio 


Mac OS X Windows Linux 
Text Widgets 
Text widgets are created using the Text function: 
text = Text(parent, width=40, height=10) 
While we briefly introduced text widgets in an earlier chapter, here we'll go into much more detail, 


to give you a sense of the level of sophistication it allows. Still, for any significant work with the 
text widget, the reference manual is very well organized and useful. 


The Basics 


If you just want to use the text widget to get a simple multi-line text from the user as part of a form, 
there's only a few things you'll need to worry about: creating and sizing the widget (check), 
providing an initial value for the text in the form, and retrieving the text in the widget after the user 
has submitted the form. 
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Providing Initial Content 

When you first create it, the text widget has nothing in it, so if you want to provide an initial piece 
of text, you're going to have add it yourself. Unlike for example the entry widget, text widgets don't 
support a "textvariable" configuration option; as we'll soon see, text widgets can contain a lot 
more than just plain text, so a simple variable isn't sufficient to hold it all. 


Instead, to set the initial text for the widget, you'll use the widget's "insert" method: 


text.insert('1.0', 'here is my text to insert') 


The "1.0" here represents where to insert the text, and can be read as "line 1, character 0". This 
refers to the first character of the first line; for historical conventions related to how programmers 
normally refer to lines and characters, line numbers are 1-based, and character numbers are O-based. 


The text to insert is just a string. Because the widget can hold multi-line text, the string you supply 
can be multi-line as well. To do, simply embed "An" (newline) characters in your string at the 
appropriate locations. 


Scrolling 


Scrollbars, both horizontal and vertical, can be attached to the text widget. This works exactly the 
same as using scrollbars in any other widget, such as a listbox or canvas. 


You can also ask the widget to ensure that a certain part of the text is visible. For example, if you've 
added more text to the widget than will fit onscreen (so it will scroll) but want to ensure that the top 
of the text rather than the bottom is visible, call the "see" method, passing it the position of the 
text (e.g. "1.0". 


Controlling Wrapping 

What if some lines of text in the widget are very long, longer than the width of the widget? By 
default, text will just wrap around to the next line, but if and how it does this can be controlled by 
the "wrap" configuration option. The default value is "char", meaning wrap around right at the 
character at the end of the line; other options are "word" to cause wrapping, but only at word 
breaks (e.g. spaces), and "none" meaning don't wrap around at all. In the latter case, some of the 
text won't be visible unless you attach a horizontal scrollbar to the widget. 


Disabling the Widget 


Some forms will temporarily disable editing in particular widgets unless certain conditions are met 

(e.g. some other options are set to a certain value). To prevent the user from making any changes to 
a text widget, set the "state" configuration option to "disabled"; re-enable editing by setting 
this option back to "normal". 


Retrieving the Text 


Finally, after the user has made any changes and submitted the form, your program will want to 
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retrieve the contents of the widget, which is done with the "get" method: 


thetext = text.get('1.0', 'end') 


Modifying the Text in Code 


While the user can modify the text in the text widget interactively, your program can also make 
changes. Adding text is done with the "insert" method, which we used above to provide an 
initial value for the text widget. 


Text Positions and Indices 


When we specified a position of "1.0" (first line, first character), this was an example of an index. It 
tells the insert method where to insert the new text (just before the first line, first character, i.e. at 
the very start of the widget). There are a variety of ways to specify these indices. You've also seen 
another one: the "end" (from the "get" example) means just past the end of the text ("just past" 
because text insertions go right before the given index, so inserting at "end" will add text to the end 
of the widget). Note that Tk will always add a newline at the very end of the text widget. 


Here are a few additional examples of indices, and what they mean: 


3.end The newline at the end of line 3. 

1.0 + 3 chars Three characters past the start of line 1. 

2.end -1 chars The last character before the new line in line 2. 

end -1 chars The newline that Tk always adds at the end of the text. 

end -2 chars The actual last character of the text. 

end -1 lines The start of the last actual line of text. 

2 + 2 lines The third character (index 2) of the fourth line of text. 

5 linestart The first character of line 2. 

.5 lineend The position of the newline at the end of line 2. 
5 wordstart The first character of the word containing the character at index 2.5. 
5 


The first character just past the last character of the word containing index 
2.5. 
Some additional things to keep in mind: 


N NNN BN 


wordend 


+ The term "chars" can be abbreviated as "c", and "lines" as "1". 

e You can omit the spaces between the terms, e.g. "1.0+3c". 

e If you specify an index past the end of the widget (e.g. "end + 100c") it will be interpreted as 
the end. 

e Adding characters will wrap to the next lines as needed; e.g. "1.0 + 10 chars" on a line with 
only five characters will end up being on the second line. 

e When using indices containing multiple words, make sure to quote them appropriately so 
that Tk sees the entire index as a single argument. 
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e When moving up or down a certain number of lines, this is interpreted as logical lines, 
where each line is terminated only by the "\n". With long lines and wrapping enabled, this 
may be represent multiple lines on the display. If you'd like to move up or down a single line 
on the display, you can specify this as e.g. "1.0 + 2 display lines". 

+ To determine the actual canonical position of an index, use the "index" method, passing it 
the index expression, and it will return the corresponding index in the form "line.char". 

e You can compare two indices using the "Compare" method, which lets you check for 
equality, whether one index is later in the text than the other, etc. 


Deleting Text 


While the "insert" method adds new text anywhere in the widget, the "delete" method 
removes it. You can specify either a single character to be deleted (by index), or a range of 
characters specified by the start and end index. In the latter case, characters from (and including) the 
start index through to just before the end index will be deleted (so the character at the end index is 
not deleted). So this would remove a single line of text (including its trailing newline) from the start 
of the text: 


text.delete('1.0', '2.0') 


There is also a "replace" method, taking a starting index, and ending index and a string as 
parameters. It does the same as a delete, followed by an insert at the same location. 


Example: Logging Window 

Here's a short example illustrating how to use a text widget as a 80x24 logging window for your 
application. The user doesn't edit the text widget at all; instead, your program will write log 
messages to it. You'd like to keep the content to no more than 24 lines (so no scrolling), so as you 
add new messages at the end, you'll have to remove old ones from the top if there are already 24 
lines. 


from tkinter import * 
from tkinter import ttk 


root = Tk() 
log = Text(root, state='disabled', width=80, height=24, wrap='none' ) 
log.grid() 


def writeToLog(msg): 
numlines = log.index('end - 1 line').split('.')[0] 
log['state'] = 'normal' 
if numlines==24: 
log.delete(1.0, 2.0) 
if log.index('end-ic')!='1.0': 
log.insert('end', '\n') 
log.insert('end', msg) 
log['state'] = 'disabled' 


Note that because the widget was disabled, we had to reenable it to make any changes, even from 
our program. 
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Formatting with Tags 


Up until now, we've just dealt with plain text. Now it's time to look at how to add special 
formatting, such as bold, italic, strikethrough, background colors, font sizes, and much more. Tk's 
text widget implements these using a feature called tags. 


Tags are objects associated with the text widget. Each tag is referred to via a name chosen by the 
programmer. Each tag can have a number of different configuration options; these are things like 
fonts, colors, etc. that will be used to format text. Though tags are objects having state, they don't 
need to be explicitly created; they'll be automatically created the first time the tag name is used. 


Adding Tags to Text 

Tags can be associated with one or more ranges of text in the widget. As before, these are specified 
via indices; a single index to represent a single character, and a start and end index to represent the 
range from the start character to just before the end character. Tags can be added to ranges of text 
using the "tag add" method, e.g. 


text.tag_add('highlightline', '5.0', '6.0') 


Tags can also be provided when inserting text by adding an optional parameter to the "insert" 
method, which holds a list of one or more tags to add to the text you're inserting, e.g. 


text.insert('end', 'new material to insert', ('highlightline', 'recent', 
'warning')) 

As the text in the widget is modified, whether by the user or your program, the tags will adjust 
automatically. So for example if you had tagged the text "the quick brown fox" with the tag 


"nounphrase", and then replaced the word "quick" with "speedy", the tag would still apply to the 
entire phrase. 


Applying Formatting to Tags 
Formatting is applied to tags via configuration options; these work similarly to configuration 


options for the entire widget. As an example: 


text.tag_configure('highlightline', background='yellow', font='helvetica 14 
bold', relief='raised' ) 


The currently available configuration options for tags are: "background", "bgstipple", 
"borderwidth", "elide", "fgstipple", "font", "foreground", "justify", 
"Tmargini", "lmargin2", "offset", "overstrike", "relief", "rmargin", 
"spacingi", "spacing2", "spacing3", "tabs", "tabstyle", "underline", and 
"wrap". Check the reference manual for detailed descriptions of these. The "tag cget" method 
allows you to query the configuration options of a tag. 


94 


Because multiple tags can apply to the same range of text, there is the possibility for conflict (e.g. 
two tags specifying different fonts). A priority order is used to resolve these; the most recently 
created tags have the highest priority, but priorities can be rearranged using the "tag raise" and 
"tag lower" methods. 


More Tag Manipulations 


To delete a tag altogether, you can use the "tag delete" method. This also of course removes 
any references to the tag in the text. You can also remove a tag from a range of text using the "tag 
remove" method; even if that leaves no ranges of text with that tag, the tag object itself still exists. 


The "tag ranges" method will return a list of ranges in the text that the tag has been applied to. 
There are also "tag nextrange" and "tag prevrange" methods to search forward or 
backward for the first such range from a given position. 


The "tag names" method, called with no additional parameters, will return a list of all tags 
currently defined in the text widget (including those that may not be presently used). If you pass the 
method an index, it will return the list of tags applied to just the character at the index. 


Finally, you can use the first and last characters in the text having a given tag as indices, the same 
way you can use "end" or "2.5". To do so, just specify "tagname. first" or 
"tagname.last". 


Differences between Tags in Canvas and Text Widgets 


While both canvas and text widgets support "tags" which can be used to apply to several objects, 
style them, and so on, these tags are not the same thing. There are important differences to take note 
of. 


In canvas widgets, individual canvas items have configuration options that control their appearance. 
When you refer to a tag in a canvas, the meaning of that is identical to "all canvas items presently 
having that tag". The tag itself doesn't exist as a separate object. So in the following snippet, the last 
rectangle added will not be colored red. 


canvas.itemconfigure('important', fill='red') 
canvas.create_rectangle(10, 10, 40, 40, tags=('important')) 


In text widgets by contrast, it's not the individual characters that retain the state information about 
appearance, but tags, which are objects in their own right. So in this snippet, the newly added text 
will be colored red. 

text.insert('end', 'first text', ('important')) 


text.tag_configure('important', foreground='red' ) 
text.insert('end', 'second text', ('important')) 
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Events and Bindings 


One quite cool thing is that you can define event bindings on tags. That allows you to do things like 
easily recognize mouse clicks just on particular ranges of text, and popup up a menu or dialog in 
response. Different tags can have different bindings, so it saves you the hassle of sorting out 
questions like "what does a click at this location mean?". Bindings on tags are implemented using 
the "tag bind" method: 


text.tag_bind('important', '<1>', popupImportantMenu) 


Widget-wide binding to events works as it does for every other widget. Besides the normal low- 
level events, there are also two virtual events that will be generated: <Modified> whenever a 
change is made to the content of the widget, and <Selection> whenever there is a change made to 
which text is selected. 


Selecting Text 


Your program may want to know if a range of text has been selected by the user, and if so, what that 
range is. For example, you may have a toolbar button to bold the selected text in an editor. While 
you can tell when the selection has changed (e.g. to update whether or not the bold button is active) 
via the <Selection> virtual event, that doesn't tell you what has been selected. 


The text widget automatically maintains a tag named "sel", which refers to the selected text. 
Whenever the selection changes, the "sel" tag will be updated. So you can find the range of text 
selected using the "tag ranges" method, passing it "sel" as the tag to report on. 


Similarly, you can change the selection by using "tag add" to set a new selection, or "tag 
remove" to remove the selection. You can't actually delete the "sel" tag of course. 


Though the default widget bindings prevent this from happening, "sel" is like any other tag in that it 
can support multiple ranges, i.e. disjoint selections. To prevent this from happening when changing 
the selection from your code, make sure you remove any old selection before adding a new one. 


The text widget manages the concept of the insertion cursor (where newly typed text will appear) 
separate from the selection. It does so using a new concept called a mark. 


Marks 


Marks are used to indicate a particular place in the text. In that respect they are like indices, except 
that as the text is modified, the mark will adjust to be in the same relative location. In that way they 
are resemble tags, but refer to a single position rather than a range of text. Marks actually don't refer 
to a position occupied by a character in the text, but specify a position between two characters. 


Tk automatically maintains two different marks. The first is named "insert", and is the present 
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location of the insertion cursor. As the cursor is moved (via mouse or keyboard), the mark moves 
with it. The second mark is named "current", and reflects the position of the character underneath 
the current mouse position. 


To create your own marks, use the widget's "mark set" method, passing it the name of the mark, 
and an index (the mark is positioned just before the character at the given index). This is also used 
to move an existing mark to a different position. Marks can be removed using the "mark unset" 
method, passing it the name of the mark. If you delete a range of text containing a mark, that also 
removes the mark. 


The name of a mark can also be used as an index (in the same way "1.0" or "end-1c" are indices). 
You can find the next mark (or previous one) from a given index in the text using the "mark 
next" or "mark previous" methods. The "mark names" method will return a list of the 
names of all marks. 


Marks also have a gravity, which can be modified with the "mark gravity" method, which 
affects what happens when text is inserted at the mark. Suppose we have the text "ac", with a mark 
in between that we'll symbolize with a pipe, i.e. "alc". If the gravity of that mark is "right" (the 
default) the mark will attach itself to the "c". If the new text "b" is inserted at the mark, the mark 
will remain stuck to the "c", and so the new text will be inserted before the mark, i.e. "able". If the 
gravity is instead "left", the mark will attach itself to the "a", and so new text will be inserted after 
the mark, i.e. "albc". 


Images and Widgets 
Like canvas widgets, text widgets can contain not only text, but also images and any other Tk 
widgets (including a frame itself containing many other widgets). In some senses, this allows the 


text widget to work as a geometry manager in its own right. The ability to add images and widgets 
within the text opens up a world of possibilities for your program. 

Images are added to a text widget at a particular index, with the image normally specified as an 
existing Tk image. There are also other options that allow you to fine-tune padding and so on. 
flowers = PhotoImage(file='flowers.gif' ) 


text.image_create('sel.first', image=flowers) 


Widgets are added to a text widget pretty much the same way as images. The widget you're adding 
should be a descendant of the text widget in the overall window hierarchy. 


b = ttk.Button(text, text='Push Me') 
text .window_create('1.0', window=b) 
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Even More 


There are many more things that the text widget can do; here we'll briefly mention just a few more 
of them. For details on using any of these, see the reference manual. 


Search 


The text widget includes a powerful "search" method which allows you to locate a piece of text 
within the widget; this is useful for a "Find" dialog, as one obvious example. You can search 
backwards or forwards from a particular position or within a given range, specify your search using 
exact text, case insensitive, or using regular expressions, find one or all occurrences of your search 
term, and much more. 


Modifications, Undo and Redo 

The text widget keeps track of whether or not changes have been made to the text (useful to know 
whether you need to save it for example), which you can query (or change) using the "edit 
modified" method. There is also a complete multi-level undo/redo mechanism, managed 
automatically by the widget when you set its "undo" configuration option to true. Calling "edit 
undo" or "edit redo" then will modify the current text using information stored on the 
undo/redo stack. 


Eliding Text 

You can actually include text in the widget that is not displayed; this is known as "elided" text, and 
is made available using the "elide" configuration option for tags. You can use this to implement 
for example an outliner, a "folding" code editor, or even just to bury some extra meta-data 
intermixed with your text. When specifying positioning with elided text you have to be a bit more 
careful, and so commands that deal with positions have extra options to either include or ignore the 
elided text. 


Introspection 

Like most Tk widgets, the text widget goes out of its way to expose information about its internal 
state; we've seen most of this in terms of the "get" method, widget configuration options, 
"names" and "cget" for both tags and marks, and so on. There is even more information 
available that you can use for a wide variety of tasks. Check out the "debug", "dlineinfo", 
"bbox", "count" and "dump" methods in the reference manual. 


Peering 


The Tk text widget allows the same underlying text data (containing all the text, marks, tags, 
images, and so on) to be shared between two or more different text widgets. This is known as 
peering, and is controlled via the "peer" method. 
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Tree 


e Widget Roundup 
e Reference Manual 


A treeview widget can display and allow browsing through a hierarchy of items, and can show one 
or more attributes of each item as columns to the right of the tree. It allows you to build user 
interfaces similar to the tree display you'd find in file managers like the OS X Finder or Windows 
Explorer. As with most Tk widgets, there is a ton of flexibility to make it behave as you need for a 
wide range of situations. 


Size Modified Size Modified 
widgets 25KB Yesterday widgets 25KB Yesterday i 25KB Yesterday 
R q. aoe erre ci gallery 2KB Two weeks ago 2KB Two weeks ago 
f r f 
č ed liada 3 resources 220KB Three weeks ago 220KB Three weeks ago 
tutorial 2.1MB Ten minutes ago > 7 2.1M8 Ten minutes ago 
canvas 18KB Last k 3 tutorial 2.1MB Ten minutes ago 
18KB Last week 
tree SKB Ten minutes ago 


SKB Ten minutes ago 
12KB Yesterday 


text 12KB Yesterday Ten minutes ago 
Yesterday 


Mac OS X Windows Linux 
Treeview Widgets 
Treeview widgets are created using the ttk . Treeview function: 


tree = ttk.Treeview(parent ) 


Horizontal and vertical scrollbars can be added in the usual manner, if desired. 


Adding Items to the Tree 


To do anything useful with the treeview, you'll need to add one or more items to it. Each item 
represents a single node in the tree, whether a leaf node or an internal node. Items are referred to by 
a unique id; this can be assigned by the programmer when the item is first created, or the widget can 
automatically choose an id for the item. 


Items are created by inserting them into the tree, using the treeview's '"insert" method. To insert 
an item, you need to know where in the tree to insert it, which means specifying the parent item as 
well as what position in the list of the parent's children the new item should be inserted at. 


The treeview widget automatically creates a root node (which is not displayed), having the id of 
"{}" (i.e. the empty string), which can serve as the parent of the first level of items you add. 
Positions within the list of the parent's children are specified by index (0 being the first, with the 
special "end" index meaning inserting after all existing children). 


Normally, you'll also specify the name of each item, which is displayed in the tree. There are other 
options to add an image beside the name, specify whether the node is open or closed, and so on. 
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+ Inserted at the root, program chooses id: 
tree.insert('', 'end', 'widgets', text='Widget Tour') 


+ Same thing, but inserted as first child: 
tree.insert('', ©, 'gallery', text='Applications') 


+ Treeview chooses the id: 
id = tree.insert('', 'end', text='Tutorial') 


# Inserted underneath an existing node: 


tree.insert('widgets', 'end', text='Canvas') 
tree.insert(id, 'end', text='Tree') 


Inserting the item returns the id of the newly created item. 


Rearranging Items 


A node (and its descendants, if any) can be moved to a different location in the tree; the only 
restriction is that a node cannot be moved underneath one of its descendants. The target location is 
specified via parent and index into the list of children, as was done with "insert". 


tree.move('widgets', 'gallery', 'end') # move widgets under gallery 
Items can be detached from the tree, which removes the item and its descendants from the 
hierarchy, but does not destroy the items, allowing you to later reinsert them with "move". 


tree.detach('widgets' ) 


Items can also be deleted, which does completely get rid of the item and its descendants. 


tree.delete('widgets') 
If you'd like to navigate the hierarchy, there are methods that let you find the parent of an item 


("parent"), find the next or previous siblings of an item ("next" and "prev'"), and return the 
list of children of an item ("children"). 


You can control whether or not the item is open and shows its children by modifying the "open" 
item configuration option. 


tree.item('widgets', open=TRUE) 
isopen = tree.item('widgets', 'open') 


Displaying Information for each Item 


The treeview can also display one or more additional pieces of information about each item, which 
are shown as columns to the right of the main tree display. 


Again, each column is referenced by a symbolic name that you assign. You can specify the list of 
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columns using the "columns" configuration option of the treeview widget, either when first 
creating the widget, or later on. 


tree = ttk.Treeview(root, columns=('size', 'modified')) 

tree['columns'] = ('size', 'modified', 'owner') 

You can specify the width of the column, how the display of item information in the column is 
aligned, and more. You can also provide information about the heading of the column, such as the 
text to display, an optional image, alignment, and a script to invoke when the item is clicked (e.g. to 
sort the tree). 


tree.column('size', width=100, anchor='center' ) 
tree. heading('size', text='Size') 


The values to place in each column for each item can be specified either individually, or by 
providing a list of values for the item. In the latter case, this is done using the "values" item 
configuration option (and so can be used either when first inserting the item or later) which takes a 
list of the values; the order of the list must be the same as the order in the "Columns" widget 
configuration option. 

tree.set('widgets', 'size', '12KB') 


size = tree.set('widgets', 'size') 
tree.insert('', 'end', text='Listbox', values=('15KB Yesterday mark')) 


Item Appearance and Events 


Like the text and canvas widgets, the treeview widget uses tags to help you modify the appearance 
of items in the tree. You can assign a list of tags to each item using the "tags" item configuration 
option (again, when creating the item or later on). 


Tag configuration options can then be specified, which will then apply to all items having that tag. 
Valid tag options include "foreground" (text color), "background", "font", and 


"image" (not used if the item specifies its own image). 


You can also create event bindings on tags, which let you capture mouse clicks, keyboard events 
etc. 


tree.insert('', 'end', text='button', tags=('ttk', 'simple')) 
tree.tag_configure('ttk', background='yellow') 

tree.tag_bind('ttk', '<1>', itemClicked) # the item clicked can be found via 
tree. focus() 


The treeview will generate virtual events "<TreeviewSelect>", "<Treeview0pen>" and 
"<TreeviewClose>" which allow you to monitor changes to the widget made by the user. You 
can use the "selection" method to determine the current selection (the selection can also be 
changed from your program). 
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Customizing the Display 
There are many aspects of how the treeview widget is displayed that you can customize. Some of 


them we've already seen, such as the text of items, fonts and colors, names of column headings, and 
more. Here are a few additional ones. 


e Specify the desired number of rows to show using the "height" widget configuration 
option. 

e Control the width of each column using the column's "width" or "minwidth" options. 
The column holding the tree can be accessed with the symbolic name "#0". The overall 
requested width for the widget is based on the sum of the column widths. 

e Choose which columns to display and the order to display them in using the 
"displaycolumns" widget configuration option. 

e You can optionally hide one or both of the column headings or the tree itself (leaving just the 
columns) using the "show" widget configuration option (default is "tree headings" to show 
both). 

e You can specify whether a single item or multiple items can be selected by the user via the 
"selectmode" widget configuration option, passing "browse" (single item), 
"extended" (multiple items, the default), or "none". 


Styles and Themes 


The "themed" aspect of the new Ttk widgets is one of the most powerful and exciting aspects of the 
new widget set. Yet because it does things quite differently from how Tk has traditionally worked, 
and because in trying to be flexible it does a lot of things, it's certainly the most confusing for many 
people. 


Definitions 


We'll first define a few concepts and terms that Ttk themes and styles rely on. 


Widget Class 

A widget class is used by Tk to identify the type of a particular widget; essentially, whether it is a 
button, a label, a canvas, etc. In classic Tk, all buttons had the same class ("Button"), all labels had 
the same class ("Label"), etc. 


You could use this widget class both for introspection, and for changing options globally via the 
option database. This could let you say for example that all buttons by default had a red 
background. 


There were a few classic Tk widgets, including frame and toplevel widgets, which would allow you 
to change the widget class of a particular widget when the widget was first created, by passing it a 
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"class" configuration option. So while normally frames would have a widget class of "Frame", 


you could specify that one particular frame widget had a widget class of "SpecialFrame". 


Because of that, you could use the option database to define different looks for different types of 
frame widgets (not just all frame widgets, or frame widgets located at a particular place in the 
hierarchy). 


What Ttk does is take that simple idea and give it rocket boosters. 


Widget State 


A widget state allows a single widget to have more than one apperance or behavior, depending on 
things like mouse position, different state options set by the application, and so on. In classic Tk, 
several widgets had "state" configuration options which allowed you to set them to "normal" or 
"disabled"; a "disabled" state for a button for example would draw its label greyed out. Some used 
an additional state, "active", again which represented a different behavior. 


The widget itself, or more typically, the widget's class bindings, controlled how the appearance of 
the widget changed in different states, typically via consulting widget configuration options like 
"foreground", "activeforeground", and "disabledforeground". 


Ttk again extends and generalizes this basic idea of widget state, in two important ways. First, 
rather than being widget-specific, all Ttk widgets have state options, and in fact, all have exactly the 
same state options, accessed by the "state" and "instate" widget commands. 


A Ttk widget state is actually a set of independent state flags, containing zero or more of the 
following flags: "active", "disabled", "focus", "pressed", "selected", 
"background", "readonly", "alternate", or "invalid" (see the widget page in the 
reference manual for exact meanings). 


Note that while all of these state flags are available for every widget, they may not be used by each 
widget. For example, a label widget is likely to ignore an "invalid" state flag, and so no special 
appearance would be associated with that flag. 


The second major change that Ttk makes is that it takes the decision of what to change when the 
state is adjusted out of the widget's control. That is, a widget author will no longer hardcode logic to 
the effect of "when the state is disabled, consult the disabledforeground configuration option and 
use that for the foreground color". With that logic hardcoded, not only did it make coding widgets 
longer (and more repetitive), but also restricted how a widget could be changed based on its state. 
That is, if the widget author hadn't coded in logic to change the font when the state changed, you as 
the user of the widget were out of luck. 


Instead of hardcoding these decisions within each widget, Ttk moves the decisions into a separate 
location: styles. This means that the widget author doesn't need to provide code for every possible 
appearance option, which not only simplifies the widget, but paradoxically ensures that a wider 
range of appearances can be set, including those the widget author may not have anticipated. 
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Style 

That brings us then to define a widget style. Very simply, a style describes the appearance (or 
appearances) of a Ttk widget class. All widgets created with that widget class will have the same 
appearance(s). While each themed widget has a default class (e.g. "TButton" for "ttk::button" 
widgets), you can, unlike in classic Tk, assign a different widget class for any themed widget you 
create. This is done using Ttk's "style" configuration option, which all themed widgets support. 


So a style defines the normal appearance of widgets of a certain widget class, but can also define 
variations of that appearance that depend on the current state flag. So for example a style can 
specify that when the "pressed" state flag is set, the appearance should change in a particular way. 
Because of this, a style can describe one or more ways for the widget to appear, depending on the 
state. 


The rest of this chapter will delve into far more detail of what a style actually is, but at least now 
you know the responsibility it has. 


Themes 


You can think of a theme as a collection of styles. While each style is widget-specific (one for 
buttons, one for entries, etc.) a theme will collect many styles together. Typically, a theme will then 
define one style for each type of widget, but each of those styles will be designed so that they 
visually "fit" together with each other — though perhaps unfortunately Ttk doesn't technically 
restrict bad design or judgement! 


To use a particular theme for an application is really to say that you'd like to have a set of styles 
defined so that by default all the different type of widgets will have some common appearance, and 
fit in well with each other. 


Using Styles and Themes 


So now we know what styles and themes are supposed to do, but how exactly do we use them? To 
do this, we need to know how to refer to styles and themes, and how to apply them to a widget or 
user interface. 


Style Names 
Every style has a name. If you're going to modify a style, create a new one, or use a style for a 


widget, you need to know its name. 


How do you know what the names of the styles are? If you have a particular widget, and you want 
to know what style it is currently using, you can first check the value of its "style" configuration 
option. If that is empty, it means the widget is using the default style for the widget. You can 
retrieve that via the widget's class. For example: 


>>> b = ttk.Button() 
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>>> b['style'] 
>>> b.winfo_class() 


'TButton' 


So in this case, the style that is being used is "TButton". The default styles for other themed widgets 
are named similarly, e.g. "TEntry", "TLabel", "TSizeGrip", etc. It's always wise to check specifics 
though; for example, the treeview widget's class is "Treeview", not "TTreeview". 


Beyond the default styles though, styles can be named pretty much anything. You might create your 
own style (or use a theme that has a style) named "FunButton", "NuclearReactorButton", or even 
"GuessWhatlAm" (not a smart choice). More often, you'll find names like "Fun.TButton" or 
"NuclearReactor.TButton", which suggest variations of a base style; as you'll see, this is something 
Ttk supports for creating and modifying styles. 


The ability to retrieve a list of all currently available styles is currently not supported. 


Using a Style 

To use a style means to apply that style to an individual widget. If you know the name of the style 
you want to use, and which widget to apply it to, it's easy. Setting the style can be done at creation 
time: 


b = ttk.Button(parent, text='Hello', style='Fun.TButton') 


As well, you can change the style of a widget at anytime after you've created it with the "style" 
configuration option: 


b['style'] = 'NuclearReactor.TButton' 


Using Themes 

While styles control the appearance of individual widgets, themes control the appearance of the 
entire user interface. The ability to switch between themes is one of the significant features of the 
themed widgets. 


Like styles, themes are identified by a name. You can obtain the names of all available themes: 


>>> s = ttk.Style() 
>>> s.theme_names() 
('aqua', 'step', 'clam', 'alt', 'default', 'classic') 


Only one theme can ever be active at a time. To obtain the name of the theme currently in use, you 
can use the following: 


This API, which was originally targeted for Tk 8.6, was back-ported to Tk 8.5.9. If you're using an 
earlier version of Tk getting this info is a bit trickier. 


>>> s.theme_use() 
'aqua' 


Switching to a new theme can be done with: 
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s.theme_use('themename' ) 


What does this actually do? Obviously, it sets the current theme to the indicated theme. Doing this 
therefore replaces all the currently available styles with the set of styles defined by the theme. 
Finally, it refreshes all widgets, so that they take on the appearance described by the new theme. 


What's Inside a Style? 


If all you want to do is use a style, you now know everything you need. If however, you want to 
create your own styles, or modify an existing one, now it gets "interesting". 


Elements 


While each style represents a single widget, each widget is normally composed of smaller pieces, 
called elements. It's the job of the style author to construct the entire widget out of these smaller 
elements. What these elements are depends on the widget. 


Here's an example of a button. It might have a border on the very outside, which is one element. 
Just inside that there may be a focus ring, which is normally just the background color but may be 
highlighted when the user tabs into the button. So that's a second element. Then there might be 
some spacing between that focus ring and the button's label. So that spacing would be a third 
element. Finally, there is the label of the button itself, a fourth element. 


Focus ring element 


Spacing element 


Label 


Label element 


Border element 


Possible Elements of a Button. 


Why might the style author have divided it up that way? If you have one part of the widget that may 
be in a different location from another, or might be a different color than another, it may be a good 
candidate for an element. Note that this is just one example of how a button could be constructed 
from elements. Different styles and themes could (and do) accomplish this in different ways. 


Here is a second example of a vertical scrollbar, containing a "trough" element containing the rest, 
which includes the up and down arrow elements at either end, and a "thumb" element in the middle. 
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Arrow element 


Thumb element Trough element 


Arrow element 


Possible Elements of a Scrollbar. 


Layout 


Besides the choice of which elements are part of a widget, a style also defines how those elements 
are arranged within the widget, or in other words, their layout. In the button example, we had a label 
element inside a spacing element, inside a focus ring element, inside a border element. So the 
logical layout is like this: 


border { 
focus { 
spacing { 
label 
} 
} 
} 


We can ask Ttk what the layout of the TButton style is like this: 


>>> s,layout('TButton') 

[("Button.border", {"children": [("Button.focus", {"children": 
[("Button.spacing", 

{"children": [("Button.label", {"sticky": "nswe"})], "sticky": "nswe"})], 
"sticky": "nswe"})], "sticky": "nswe", "border": "1"})] 


If we clean this up and format it a bit, we get something with this structure: 


Button.border -sticky nswe -border 1 -children { 
Button.focus -sticky nswe -children { 
Button.spacing -sticky nswe -children { 
Button. label -sticky nswe 
} 
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} 


This starts to make sense; we have four elements, named "Button.border", "Button.focus", 
"Button.spacing", and "Button.label". Each of these has different element options, such as "- 


children", "-sticky", and "-border" that here specify layout or sizes. Without getting into two much 
detail at this point, we can clearly see the nested layout, based on the "-children" and "-sticky" 
attributes; Ttk uses a simplified version of Tk's "pack" geometry manager to specify element layout. 


Element Options 


Each of these different elements may have a number of different options. For example, the thumb of 
the scrollbar may have an option to set its background color, or another to provide the width of a 
border, if any. These can be customized to adjust how the elements within the widget look. 


What options are available for each element? Here's an example of checking what options are 
available for the label inside the button (which we know from the "layout" command is identified as 


"Button.label"): 

>>> s.element_options('Button.label') 

('-compound', '-space', '-text', '-font', '-foreground', '-underline', '-width', 
'-anchor', '-justify', 

'-wraplength', '-embossed', '-image', '-stipple', '-background') 


Presumably these options shouldn't have the leading dash on them. 


In the next sections, we'll take a look at the not-entirely-straightforward way that you can work with 
element options. 


Changing Style Options 
In this section, we'll look at how you can change the style's appearance via modifying style options. 
You can do this either by modifying an existing style, or more typically, by creating a new style. 


Modifying a Style Option 
Modifying a configuration option for an existing style is done in a similar fashion as modifying any 
other configuration option, by specifying the style, name of the option, and new value: 


s.configure('TButton', font='helvetica 24') 
You'll learn more about what the valid options are shortly. 


If you need to retrieve the current value of an option, this can be done with the "lookup" method. 


>>> s.lookup('TButton', 'font') 
'helvetica 24' 
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Creating a New, Derived Style 


If you modify an existing style, such as "TButton", that modification will apply to all widgets using 
that style (so by default, all buttons). That may well be what you want to do. 


More often, you're interested in creating a new style that is similar to an existing one, but varies in a 
certain aspect. For example, you'd like to have most of the buttons in your application keep their 
normal appearance, but create certain special "emergency" buttons, which will be highlighted in a 
different way. In this case, creating a new style (e.g. "Emergency. TButton") derived from the base 
style ("TButton") would be the appropriate thing to do. 


By prepending another name ("Emergency") followed by a dot onto an existing style, you are 
implicitly creating a new style derived from the existing one. So in this example, our new style will 
have exactly the same options as a regular button except for the indicated differences: 


s.configure('Emergency.TButton', font='helvetica 24', 
foreground='red', padding=10) 


State Specific Style Options 

Besides the normal configuration options for the style, the widget author may have specified 
different options to use when the widget is in a particular widget state. For example, when a button 
is disabled, you'd like to have the color of the button's label greyed out. 


To do this, you can specify a "map", which allows you to specify variations for one or more of a 
style's configuration options. For each configuration option, you can specify a list of widget states, 
along with the particular value the option should be assigned when the widget is in that state. 


Remember that the state is composed of one or more state flags (or their negation), as set by the 
widget's "state" method, or queried via the "instate" method. 


The following example provides for the following variations from a button's "normal" appearance: 


e when the widget is in the disabled state, the background color should be set to "#d9d9d9" 

e when the widget is in the active state (mouse over it), the background color should be set to 
"#ececec" 

e when the widget is in the disabled state, the foreground color should be set to "#a3a3a3" 
(this is in addition to the background color change we already noted) 

e when the widget is in the state where the button is pressed and the widget is not disabled, the 


relief should be set to "sunken" 
s.map('TButton', 
background=[('disabled', '#d9d9d9), ('active', '#ececec)], 


foreground=[('disabled', '#a3a3a3')], 
relief=[('pressed', '!disabled', 'sunken')]) 


Remember that in the past, with classic Tk widgets, exactly what changed when the widget was in 
each state would have been determined solely by the widget author. With themed widgets, it is the 
style itself that determines what changes, which could include things that the original widget author 
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had never anticipated. 


Because widget states can contain multiple flags, it's possible that more than one state will match 
for an option (e.g. "pressed" and "pressed !disabled" will both match if the widget's "pressed" state 
flag is set). The list of states is evaluated in the order you provide in the map command, with the 
first state in the list that matches being used. 


Sound Difficult to you? 


So you now know that styles are made up of elements, which have a variety of options, and are 
composed together in a particular layout. You can change various options on styles, to make all 
widgets using the style appear differently. Any widgets using that style take on the appearance that 
the style defines. Themes collect an entire set of related styles, making it easy to change the 
appearance of your entire user interface. 


So what makes styles and themes so difficult in practice? Three things. First: 


You can only modify options for a style, not element options (except sometimes). 


We talked earlier about how to discover what elements were used in the style by examining the 
style's layout, and also how to discover what options were available for each element. But when we 
went to make changes to a style, we seemed to be configuring an option for the style, without 
specifying an individual element. What's going on? 


Again, using our button example, we had an element "Button.label", which among other things had 
a "font" configuration option. What happens is that when that "Button.label" element is drawn, it 
looks at the "font" configuration option set on the style to determine what font to draw itself in. 


To understand why, you need to know that when a style includes an element as a piece of it, that 
element does not maintain any (element-specific) storage. In particular, it does not store any 
configuration options itself. When it needs to retrieve options, it does so via the containing style, 
which is passed to the element. Individual elements therefore are "flyweight" objects in GoF pattern 
parlance. 


Similarly, any other elements will lookup their configuration options from options set on the style. 
What if two elements use the same configuration option (like a background color)? Because there is 
only one background configuration option, stored in the style, that means both elements will use the 
same background color. You can't have one element use one background color, and the other use a 
different background color. 


Except when you can. There are a few nasty, widget-specific things called "sublayouts" in the 
current implementation which let you sometimes modify just a single element, via configuring an 
option like "TButton.Label" (rather than just "TButton", the name of the style). Are the cases where 
you can do this documented? Is there some way to introspect to determine when you can do this? 
No to both. This is one area of the themed widget API that I definitely expect to evolve over time. 
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The second difficulty is also related to modifying style options: 


Options that are available don't necessarily have an effect, and it's not an error to 
modify a bogus option. 


You'll sometimes try to change an option that is supposed to exist according to element options, but 
it will have no effect. As an example, you can't modify the background color of a button in the 
"aqua" theme used by Mac OS X. While there are valid reasons for these cases, at the moment its 
not easy to discover them, which can make experimenting frustrating at times. 


Perhaps more frustrating when you're experimenting is that specifying an "incorrect" style name or 
option name does not generate an error. When doing a "configure" or "lookup" you can in fact 
specify any name at all for a style, and specify any name at all for an option. So if you're bored with 
the "background" and "font" options, feel free to configure a "dowhatimean" option. It may not do 
anything, but it's not an error. Again, it may make it hard to know what you should be modifying 
and what you shouldn't. 


This is one of the downsides of having a very lightweight and dynamic system. You can create new 
styles by just providing their name when configuring style options; this means you don't need to 
explicitly create a style object. At the same time, this does open itself to errors. It's also not possible 
to find out what styles currently exist or are used. And because style options are really just a front 
end for element options, and the elements in a style can change at any time, it's not necessarily 
obvious that options should be restricted to those referred to by current elements alone, which may 
themselves not all be introspectable. 


Finally, here is the last thing that makes styles and themes so difficult: 


The elements available, the names of those elements, which options are available or 
have an effect for each of those elements, and which are used for a particular 
widget can be different in every theme. 


So? Keep in mind among other things that the default theme for each platform (Windows, Mac OS 
X, and Linux) are different, (which is a good thing). Some implications of this: 


1. If you want to define a new type of widget (or more likely a variation of an existing widget) 
for your application, you're going to need to do it separately and differently for each theme 
your application uses (so at least three for a cross-platform application). 

2. The elements and options available will differ for each theme/platform, meaning you may 
have to come up with a quite different customization approach for each theme/platform. 

3. The elements, names, and element options available with each theme are not typically 
documented (outside of reading the theme definition files themselves), but are generally 
identified via theme introspection (which we'll see soon). Because all themes aren't available 
on all platforms (e.g. "aqua" will only run on Mac OS X), you'll need ready access to every 
platform and theme you need to run on. 


As an example, here is what the layout of the "TButton" style looks like on the theme used by 
default on three different platforms, as well as the advertised options for each element (not all of 
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which have an effect): 


Button.button -sticky nswe -children {Button.padding -sticky nswe -children 
{Button.label -sticky nswe}} 


Button.button  - 


Mac OS X 


Button.padding padding, relief, shiftrelief 


compound, space, text, font, foreground, underline, width, anchor, 


Button. label justify, wraplength, embossed, image, stipple, background 


Button.button -sticky nswe -children {Button.focus -sticky nswe -children 


Windows {Button.padding -sticky nswe -children {Button. label -sticky nswe}}} 
Button.button - 
Button.focus - 
Button.padding padding, relief, shiftrelief 
compound, space, text, font, foreground, underline, width, anchor, 
Button.label Oaks . ] 
justify, wraplength, embossed, image, stipple, background 
inne Button.border -sticky nswe -border 1 -children {Button.focus -sticky nswe -children 


{Button.padding -sticky nswe -children Button.label -sticky nswe}}} 
Button.border background, borderwidth, relief 

Button.focus focuscolor, focusthickness 

Button.padding padding, relief, shiftrelief 


compound, space, text, font, foreground, underline, width, anchor, 
justify, wraplength, embossed, image, stipple, background 
The bottom line is that in classic Tk, where you had the ability to modify any of a large set of 


Button.label 


attributes for an individual widget, you'd be able to do something on one platform and it would 
sorta kinda work (but probably need tweaking) on others. In themed Tk, the easy option just isn't 
there, and you're pretty much forced to do it the right way if you want your application to work with 
multiple themes/platforms. It's more work up front. 


Advanced: More on Elements 


While that's about as far as we're going to go on styles and themes in this tutorial, for curious users 
and those who want to delve further into creating new themes, we can provide a few more 
interesting tidbits about elements. 


Because elements are the building blocks of styles and themes, it begs the question of "where do 
elements come from?" Practically speaking, we can say that elements are normally created in C 
code, and conform to a particular API that the theming engine understands. 


At the very lowest level, elements come from something called an element factory. At present, there 
is a "default" one, which most themes use, and uses Tk drawing routines to create elements. A 
second allows you to create elements from images, and is actually accessible at the script level 
using the "ttk::style element create" method (from Tcl). Finally, there is a third, 
Windows-specific engine using the underlying "Visual Styles" platform API. 
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If a theme uses elements created via a platform's native widgets, the calls to use those native 
widgets will normally appear within that theme's element specification code. Of course, themes 
whose elements depend on native widgets or API calls can only run on the platforms that support 
them. 


Themes will then take a set of elements, and use those to assemble the styles that are actually used 
by the widgets. And given the whole idea of themes is so that several styles can share the same 
appearance, it's not surprising that different styles share the same elements. 


So while the "TButton" style includes a "Button.padding" element, and the "TEntry" style includes 
a "Entry.padding" element, underneath these padding elements are more than likely one and the 
same. They may appear differently, but that's because of different configuration options, which as 
we recall, are stored in the style that uses the element. 


It's also probably not surprising to find out that a theme can provide a set of common options which 
are used as defaults for each style, if the style doesn't specify them otherwise. This means that if 
pretty much everything in an entire theme has a green background, the theme doesn't need to 
explicitly say this for each style. This uses a root style named "."; after all, if "Fun.TButton" can 
inherit from "TButton", why can't "TButton" inherit from "."? 


Finally, it's worth having a look at how existing themes are defined, both at the C code level in Tk's 
C library, but also via the Tk scripts found in Tk's "library/ttk" directory. Search for 
"Ttk_RegisterElementSpec" in Tk's C library to see how elements are specified. 


Case Study: IDLE Modernization 


This chapter presents a case study of modernizing the appearance of a substantial Tk-based 
application. 


This chapter is currently (November 2015) a work in progress. The code here is slowly finding its 
way into the Python source tree, but most is not there yet. You can find temporary snapshots on 
GitHub. 


IDLE (Integrated DeveLopment Environment) is the standard Python development environment 
that is bundled with every Python release. It consists of an interactive Python shell, editors with 
syntax highlighting, a debugger, etc. Its user interface is written in Tkinter. 
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File Edit Format Run Options Window Help 


dlg.deiconify() al 
dig.1ift() "| 
Ele Edit Shel Debug Options Windo destroy(self, ev=None): 
Python 3.4.0 (default, Jun 19 2015) self.dlg = None 
[GCC 4.8.2] on linux self.parent = None 
Type "copyright", "credits" or "lij 
>>> helpDialog = HelpDialog() # singleton instance 
[DEBUG ON] [def help dialog(parent): # wrapper for htest 
| helpDialog.show_dialog(parent) 
============= RUN /tmp/id) 


class EditorWindow(object): 

| from idlelib.Percolator import Percolator 
from idlelib.ColorDelegator import ColorDelegator 
from idlelib.UndoDelegator import UndoDelegator 
trom idlelib.IOBinding import IOBinding, filesyste 
from idlelib import Bindings 
from tkinter import Toplevel 
from idlelib.MultiStatusBar import MultiStatusBar 


help url = None 


e, key=! 


| k E 
Go | : ; 2 JaA z a efix, '! 
e of st. 


1.33" 4 ; 


7 /python 
'bdb'.run(), line 431: exec(cmd, globals, locals) Frthon/im f% 


> '_main_'.<module>(), line 1674: 'slash': '/', E Col: 53 


Search Dialog 


Fins Pod 
close 
! Regular expression ' Match case | Whole word Wrap around Find Next 


Overview of IDLE user interface (on Linux) 


IDLE was never intended to be a replacement for more full-featured development environments. 
Because it is relatively simple and integrated, and because it is bundled with Python, it is popular 
for those learning (and teaching) the language. 


Originally created by Python BDFL Guido van Rossum in 1998, IDLE has been incrementally 
added to over the years by multiple other developers. But with limited development effort spent on 
it, it was showing its age, especially on platforms (e.g. Mac OS X) infrequently used by those 
improving IDLE. 
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A Python Central comparison of IDE's described IDLE this way: 


All those features are in fact present, but they do not really make an IDE. In fact, while 
IDLE offers some of the features you expect from an IDE, it does so without even being 
a satisfactory text editor. The interface is buggy and fails to take into account how 
Python works, especially in the interactive shell, the auto-completion is useless outside 
the standard library, and the editing functionality is so limited that no serious Python 
programmer — heck, no serious typist — could use it full-time. 


If you use an IDE, it should not be IDLE. 


With its buggy and dated user interface, IDLE was at some risk of being removed from the Python 
distribution altogether. Yet, because of the relative simplicity and it being bundled, there were a 
number of people, particularly those teaching Python, eager to see IDLE leap forward. 


IDLE was obviously a great candidate to be modernized, using newer Tk features like the themed 
widgets to help spur some redesign. But it was about more than just swapping widgets. Many 
improvements could be made just by changing how the "classic" widgets were being used, to better 
reflect a more modern design aesthetic. 


Because IDLE, which is an application, was a part of Python's standard library (i.e. 99% designed 
to be used by other code), there were many policies and procedures not really appropriate for an 
application that made changes difficult. Removing some of those roadblocks (see PEP 434) was a 
significant step required for the types of changes being discussed here. 


Project Goals 


As you can imagine, modernizing a large application like this, based on "classic" Tkinter, was not 
entirely straightforward. In this chapter, I'll walk through some of the user interface changes that 
were made and why. 


Everyone involved wanted to see IDLE look a lot better than it did, though nobody was under the 
illusion that it was going to turn into a stunning example of cutting-edge design. But something that 
fit in more, so that people could learn about Python without getting distracted by the clumsiness of 
their tools, seemed doable. 


The goal also wasn't to try to compete with Python IDE's more commonly used by professional 
programmers, such as PyCharm, WingIDE, PyDev, Komodo, etc. Though some more experienced 
Python developers did use IDLE, either sporadically or regularly, it primarily needed to appeal to 
newcomers to the language, and often those new to programming altogether. 


There have been no shortage of previous attempts to radically advance IDLE, resulting in a number 
of different forks that boasted all kinds of improvements. Many of them used other GUI toolkits or 
modules that weren't part of the standard library. It was important here to stay with Tkinter and the 
standard library, because we wanted to ensure every improvement could over time make it into the 
official version that ships with Python, rather than becoming just another fork. 
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As well, the hope was to make IDLE easier to contribute to. This suggested pruning down a 
substantial volume of code, removing some redundancies and inconsistencies, cleaning up some of 
the more complex pieces, simplifying interactions between system components, etc. There was also 
a fairly substantial list of reported bugs that we hoped to make a dent in. 


While no less important, I'll largely defer discussion of the substantial issues surrounding software 
architecture, backwards compatibility (including for systems running Tk 8.4, pre-ttk, which 
received only a few selective improvements), etc. 


Throughout this chapter, you'll find links to individual issues in Python's issue tracking system, 
which often provide additional insight into various peoples' thought processes around changes. 


As you'll see, this chapter highlights many of the shortcomings of IDLE's user interface. This is 
done mainly for emphasis, because many of the problems shown here are common to many 
applications and user interfaces. I have only the highest respect for the people who donated their 
limited time and resources to this open source project, and had to consciously make tradeoffs 
between time, features, and user interface, all within the context of a decidedly non-trivial codebase. 


As the material in this chapter relates to a specific Python application, all the examples will be 
given solely in Python and using Tkinter. So if you're wondering why you're seeing Python code 
here where you didn't everywhere else, that's why. 


Menus 


The very first change that was made was to remove the archaic tearoff menus [Issue#13884]. The 
Mac OS X version of Tk doesn't even support them, but they were still there on Windows and X11. 


| es Python 3.4.3 Shell Python 3.4.0 Shell 


Edit Shell Debug Options Window Help File| Edit Shell Debug Options W 


fic3e601, Feb See == JE =E un 19 
` un 
ee panies i or "license | Ne" hile Ctri+N 
Ja sá Open... Ctri+0 its" or 
Recent Files » n 
Naan Madila Ale. ha Recent Files 


Tearoff menus on Windows and Linux 


The change here was to add a "tearoff=0" option to the few places in the code where these menus 
were created. 


At least that was easy. 


There were also a number of bugs where items in the menu were not being properly disabled when 
the feature was not available, leading to either menu items that did nothing (confusing for learners), 
or error dialogs that said little more than "you can't do that". 
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Main Window 


One good thing about IDLE is that, revolving around an editor and a shell, the majority of it really 
is a Tk text widget, and there was very little about ¡ts user interface that had to change. But even in 
the main window, which is mostly just a text widget, there were improvements to be had. 


The following images show the original version of IDLE's shell window, pre-modernization, just as 
someone would see when they first launched the program. 


Looking at them, what improvements would you make? 
f Python File Edit Shell Debug Options Window Help 


Python 3.4.3 Shell 


Python 3.4.3 (v3.4.3:9b73f103e601, Feb 23 2015, 02:52:03) 

[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin 

Type "copyright", "credits" or "license()” for more information. 
>>> 


| ey Python 3.4.3 Shell 

File Edit Shell Debug Options Window Help 

Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 24 2015, 22:43:06) [MSC v. | 
1600 32 bit (Intel)] on win32 

Type "copyright", "credits" or "license()" for more information. 

>>> 


ycle Bin 


‘Ln: 3|Cok: 4 


Main IDLE Window on Windows 
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pn 3.4.0 Shell 


Python 3.4.0 Shell 
File Edit Shell Debug Options Windows Help 


Python 3.4.0 (default, Jun 19 2015, 14:20:21) 

[GCC 4.8.2] on linux 

Type "copyright", "credits" or "license()" for more information. 
>>> | 


Main IDLE Window on Linux 


Default Font 


The first change that was made had to do with the default font. IDLE hardcoded 10 point Courier, 
and used that on all platforms. This didn't actually look too bad in Windows, was ok on Linux, but 
looked terrible on OS X [Issue#24745]. Sure this could be changed through a preferences dialog, 
but the defaults certainly didn't leave a good impression. 


While one option would simply be to write the code to pick a good font depending on which 
platform we're running on, instead the default was changed to use Tk's built in "TkFixedFont", 
which provides a better default on each platform. 


You can see the differences in the screen shots below. Notice how the new fonts seem to match 
better with system terminal windows that are shown. 


Python 3.4.3 (¥3.4.3:9b73f1c3e601, Feb 23 2015, 02:52:03) 

[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin 

Type "copyright", "credits" or "license()” for more information. 
>>> 


000 Python 3.4.3 Shell 


Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 23 2015, 02:52:03) 

[GCC 4.2.1 CApple Inc. build 5666) (dot 3)] on darwin 

Type "copyright", "credits" or "license()" for more information 
>>> 
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IDLE Main Window using TkFixedFont (Mac OS X) 


[ey Python 3.4.3 Shell 
File Edit Shell Debug Options Window Help 

Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 24 2015, 22:43:06) [MSC v.1600 
tel)] on win32 

Type "copyright", "credits" or "license()" for more information. 

>>> 


| es Python 3.4.3 Shell 
File Edit Shell Debug Options Window Help 


Python 3.4.3 (v3.4.3:9b73fic3e601, Feb 24 2015, 22:43:06) [MSC 
tel)] on win32 

Type "copyright", "credits" or "license()" for more informatic 
>>> | 


IDLE Main Window using TkFixedFont (Windows) 


roseman@ubuntudev: /media/sf_... X | roseman@ubuntudev: /media/sf_... x 


-oseman@ubuntudev:~$ ls /media/sf_vboxshare/ 
python idlelib notes.txt 
-oseman@ubuntudev:~$ cd /media/sf_vboxshare/ 


“ae python3 -m idlelib | 


File Edit Shell Debug Options Window Help 


Python 3.4.0 (default, Jun 19 2015, 14:20:21) 
| [GCC 4.8.2] on linux 
T "copyright", "credits" or "license()” for more information. 


| ¿ype 


Python 3.4.0 Shell 


File Edit Shell Debug Options Window Help 


Python 3.4.0 (default, Jun 19 2015, 14:20:21) 
[GCC 4.8.2] on linux 
Type "copyright", "credits" or "license()" for more informatii 
>>> | 


IDLE Main Window using TkFixedFont (Linux) 


Speaking of preferences dialogs, if you want to change the font it often helps to know what the font 
actually is (using "Font . actual"). Here's the new code from IDLE's preferences dialog that 


figures that out: 


119 


1f (family == 'TkFixedFont'): 
f = Font(name = 'TkFixedFont', exists = True, root = root) 
actualFont = Font.actual(f) 
family = actualFont['family'] 
size = actualFont['size'] 
if size < 0: 
size = 10 # if font in pixels, ignore actual size 
bold = 1 if actualFont['weight']=='bold' else 0 


For the record, the fonts that Tk chose for TkFixedFont are Monaco 11 on Mac OS X, Courier New 
10 on Windows, and DejaVu Sans Mono 10 on Linux (Ubuntu 14 to be specific). 


Around the Text Widget 


There were a few other cosmetic things that just weren't right around the edge of the main window 
[Issue#24750]. Look back at the earlier screen shots of the IDLE main window. 


Notice there's a border around the text widget. It's most noticeable on OS X where it's a dark black, 
somewhat less so on Linux, and barely perceptible on Windows. This is the result of Tk's 
"highlightthickness" attribute, which is present when the text widget has the focus. 


If the text widget doesn't have the focus, such as when the window becomes inactive, the highlight 
goes away: 


Ra 


Ln: 3 Col: 4 


Ln: 4 (Col: 4 


Mac OS X Windows Linux 
Status Bar on Inactive Window 


Notice how on the Mac OS X screenshot, without the highlight, the status bar at the bottom of the 
window blends into the text widget. Not good. 


As you'll see from looking at other applications, the border around the text widget is no longer a 
common convention. So let's start by removing that, which is as easy as adding 
"highlightthickness=0" when we create the text widget. 


That still leaves us with the problem of the status bar blending into the editor. We changed the status 
bar to be a "ttk.Frame" widget, which has a background shading on all platforms. We also 
placed a "ttk.Separator" widget just above the status bar, to give us that clean separation. 


Each of the line and column indicators were labels, previously created with: 


label = Label(self, bd=1, relief=SUNKEN, anchor=w) 


This was replaced with a "ttk. Label", to ensure it matched the frame. We also did away with 
the 1990's sunken "3d" look. 


label = ttk.Label(self) 


There's one last thing, and that's the empty space at the bottom right of the window on Mac OS X. 
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This used to be occupied by the little widget that allowed you to resize the window. Mac OS X 10.7 
added the ability to resize windows by dragging any side (like every other platform had) and did 
away with the resize widget in the corner. 


Tk provides the "ttk: :Sizegrip" widget to place in the corner if you need it, but unfortunately 
doesn't help when it comes to whether or not you need it. So that's up to you. IDLE now uses this 
code: 


def need_sizegrip(): 


Older versions of OS X in particular require a ttk::sizegrip widget 
at the bottom right corner of the window. This is no longer the case 
in more recent versions. 


if sys.platform == 'darwin': 
V, _, — = platform.mac_ver() 
major, minor = v.split('.')[:2] 
if (int(major) == 10 and int(minor) < 7): 
return True 
return False 


if need_sizegrip(): 
sz = ttk.Sizegrip(...) 


Last, but not least, we can replace the original Tk scrollbar with the newer "ttk.Scrollbar" 
widget. 


The resulting changes to the main window are shown below. Despite these being fairly minor, often 
subtle changes, they go a long way towards IDLE's main window looking a lot cleaner, more 
modern, and "just fitting in" on all platforms. 


000 Python 3.6.0a0 Shell 

Python 3.6.0a8 (default:?4fc1af5?7c?72+, Jul 31 2015, 16:41:41) 

[GCC 4.2.1 Compatible Apple LLVM 6.1.0 (clang-602.0.53)] on darwin 
Type "copyright", "credits" or "license()" for more information. 
>>> 


Ln: 4 Col: 4 


IDLE's main window, with improvements (Mac OS X) 
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File Edit Shell Debug Options Window Help 
Python 3.4.3 (v3.4.3:9b73f1c3e601, Feb 24 2015, 22:43:06) [MSC v.1600 + 
32 bit (Intel)] on win32 

Type "copyright", "credits" or "license()" for more information. 
>>> | 


IDLE's main window, with improvements (Windows) 


Python 3.4.0 Shell 
File Edit Shell Debug Options Window Help 


Python 3.4.0 (default, Jun 19 2015, 14:20:21) 
[GCC 4.8.2] on Linux 


Type "copyright", "credits" or "license()" for more information. 
>>> | 


IDLE's main window, with improvements (Linux) 


Preferences Dialog 


One visible piece that greatly needed improvement was the Preferences dialog. Again, here are 
screenshots on the three platforms: 
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eeo Settings 
Fonts/Tabs | Highlighting | Keys | General | 
Base Editor Font 


Indentation Width 
Python Standard: 4 Spaces! 
4 


MT 
2 4 6 8 10121416 


AaBbCcDdEe 
FFGgHhIiJjK 
1234567890 
#:4-O{30 


Ok Apply Cancel 


IDLE's Preferences window (Mac OS X) 
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Settings 
Fonts/Tabs | Highlighting | Keys | General | 
r Base Editor Font 


Indentation Width —————, 
Python Standard: 4 Spaces! 


Courier New - 


E IA 
2 4 6 8 10121416 


AaBbCcDdEe 
FfGgHhIiJjK 
1234567890 
#:+=() 01] 


IDLE's Preferences window (Windows) 
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Settings 


Fonts/Tabs | Highlighting | Keys | General | 


- Base Editor Font 


Font Face : 
DejaVu Sans Mono 
DejaVu Serif 
Dingbats 


Indentation Width 
Python Standard: 4 Spaces! 


Els 


2 4 6 8 10121416 


Droid Arabic Naskh 
Droid Sans 


Size: 10 =| [ Bold 


AaBbCcDdEe 
FfGgHh1iJjK 
1234567890 
#:+=(){}[] 


Ok | Apply | Cancel | 


IDLE's Preferences window (Linux) 


The other tabs allow you to modify individual colors for syntax highlighting, keystrokes assigned to 
particular operations, and a few other miscellaneous things. 


While there was some debate as to the need for this level of configuration on what was primarily a 
learning environment [Issue#24810], it seemed reasonable to at least make what was there look and 
work better before considering any more radical surgery. 


Among other things, the Preferences dialog was changed from modal (which, amusingly enough, 
didn't quite work on OS X, allowing multiple copies to be created) to modeless [Issue#24760], 
though I won't go further into that at this point. 


Tabs 


The first issue to address was the tabs used to switch between the four different preference panes. 
The original used a custom "megawidget", as classic Tk doesn't have its own widget. While the 
Windows and Linux ones don't look too bad, on recent versions of OS X there is a built-in tab 
widget that looks quite different. 


It's actually more common in Mac OS X applications now to use something similar to a toolbar 
(row of icons with labels along the top or side) to switch between preference panes, though some 
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programs do still use tabs. Tabs are very common on Windows and Linux. 


The code was modified to use the "ttk.Notebook" widget, which not only looks better on each 
platform, but allows us to jettison a lot of code for managing tabs ourselves. 


Updating Widgets 

The next obvious step was upgrading the "classic" widgets to their themed counterparts. On this 
screen, that included the buttons, labels, frames, checkbox, scrollbar, etc. There were a few others 
on some of the other panes. Generally, this was a straightforward process, often involving removing 
widget options that were no longer needed or supported by the themed widgets. 


Sometimes choosing a different widget made more sense. In this screen the option menu used for 
font size was better replaced by a combobox. Similarly, the scale widget is not commonly seen in 
today's user interfaces, and was replaced with the more familiar (and compact) spinbox widget. 


There were also various non-standard ways of using certain widgets or specifying certain types of 
data. These were generally modified to use more familiar paradigms. There were a number of 
general issues discussed relating to the design of these dialogs, e.g. [Issue#24776], [Issue#24782]. 


Layout 


While this dialog is a bad example, just given the space imbalance between the left and right halves, 
a lot of time was spent in general looking at widget spacing and alignment in dialog boxes. 


The general approach was to find similar examples in other applications, and use those as a guide. 
Where are the buttons located? How are multiple fields of a dialog organized? Where are labels 
relative to the widget they're labelling? Are they left or right aligned, capitalized, do they have a 
trailing colon? These are the sorts of questions to think about. 


A great starting point is converting from using the old 'pack' geometry manager to 'grid'. Because of 
the way it works, pack-based layouts tend to have weird and inconsistent alignment and spacing, 
especially if they've been modified over time. Using grid will increase maintainability, both because 
it uses a more familiar mental model, and because it's not dependent on the order in which widgets 
are inserted. 


It's likely impossible to come up with one layout that looks fantastic on all platforms, but often you 
can come up with one (possibly with a couple platform-specific tweaks in the code) that looks 
decent. 


A revised version of the dialog, incorporating many of the techniques here, is shown below. 


126 


000 Preferences 


¿Fonts/Tabs _ Themes Keys General Extensions 


AaBbCcDdEe 
FfGgHhliJjK 
1234567890 


#:+=000 


Font Size: 11 | Bold 


Indent: 4 |% Python Standard: 4 Spaces! 


OK Apply Cancel 


IDLE Preferences, revised version (Mac OS X) 


. 
¡Courier New Baltic 
¡Courier New CE 
¡Courier New CYR 
¡Courier New Greek 
¡Courier New TUR 
DFKai-SB 
DaunPenh 

David 

DilleniaUPC 
DokChampa 
Dotum 

DotumChe 

Ebrima 


Font Size: 10 v [E] Bold 


Indent: 4 = Python Standard: 4 Spaces! 


[ok] [amy ) [cancel | 


IDLE Preferences, revised version (Windows) 
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Preferences 


Fonts/Tabs | Themes | Keys | General | Extensions | 


DejaVu Sans Mono 2) 

DejaVu Serif 

Dingbats | 

Droid Arabic Naskh AaBbCcDdEe 
Droid Sans FfGgHh!iJjK 
Droid Sans Armenian 1234567890 
Droid Sans Ethiopic #:+=(){}[] 
Droid Sans Fallback 


Droid Sans Georgian 

Droid Sans Hebrew 

Droid Sans Japanese 

Droid Sans Mono 

Droid Sans Thai 

~ "St - r wj 


Font Size: |10 y| M Bold 


Indent: 4 # Python Standard: 4 Spaces! 


IDLE Preferences, revised version (Linux) 


Another Example 


The screenshot below shows a before and after of the IDLE Preferences pane which controls syntax 
coloring [Issue#24781]. 
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Lg Settings 


p Custom Highlighting ——_ Highlighting Theme 
Select: 


© a Built-in Theme 


(* a Custom Theme 


IDLE Classic — | 


IDLE Classic Copy — 


def func(param) : 
"""string""" Delete Custom Theme | 
var0 = 'string' 
varl 


var2 
var3 list (None) 


cursor | 
shell stdout stderr 


Save as New Custom Theme | 


IDLE Themes Pane, before (Windows) 
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Fonts/Tabs 
IDLE Classic 


IDLE New def func (param): 
"triana 
var = 'string' 
varl = 

var2 = 


var3 = list (None) 


E cursor | 


shell stdout stderr 


Python Comments 


Foreground: la] 


Background: LI 


IDLE Themes Pane, after (Windows) 


Again, substituting widgets and using more familiar conventions is one piece of this. I think the 
bigger changes have to do with thinking about things from the user perspective. Particularly as a 
beginner tool, if you're in here at all it's probably to switch themes, not tweak colors, so that is more 
dominant in the new version. It also does away with an arbitrary distinction between "built-in" and 
"custom" themes. 


I think the new version is a big improvement, though as of this writing I have yet to convince some 
people of this. This being open source, we'll see what happens! 


Other Dialogs 


There are multiple other dialog boxes in IDLE; we'll consider a couple more examples here. 


Find Dialog 


Planning on doing some more changes on these, likely combining Find and Replace into a single 
dialog. 


One of the find/search dialogs is shown below [Issue#23218], again with before and after on the 
three platforms. 
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000 Search Dialog 


Options | | Regular expression | | Match case |_| Whole word EJ Wrap around Find Next 
Direction © Up @ Down 


000 Search Dialog 


O 


Options: |_| Regular expression |_| Match case Whole word EJ Wrap around 
Direction: | Up © Down 


Close (Find! Next) 


IDLE Find Dialog, before and after (Mac OS X) 


aa | [eos 


Options: Regular expression || | Match case [|] Whole word [V] Wrap around 


Direction: © Up @ Down 


IDLE Find Dialog, before and after (Windows) 
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Search Dialog 


3 


close 


Options | Regular expression [ Match case | Whole word V Wrap around Find Next 


Direction © Up © Down 


Options: | Regular expression | Match case | Whole word X Wrap around 


Direction: Up (e Down 
= 


IDLE Find Dialog, before and after (Linux) 


The first step was upgrading the widgets to use the equivalent themed widgets. The effect of this is 
most obvious with the buttons (being consistent with the capitalization doesn't hurt either). 


Speaking of buttons, notice that in the new version, the buttons are on the right on Windows (where 
they were on all before), but at the bottom for Mac OS X and Linux. On examining multiple 
different applications our target users would likely have encountered on each platform, we found 
these locations were common. With only a few lines of extra code needed to special case for this 
layout difference, it made sense to handle things this way. 


Other aspects of the layout were also improved. Looking at the original dialogs (especially how the 
buttons don't quite line up with other widgets) I originally thought it was created with pack, and 
expected to convert it to grid. Interestingly, it was already using grid. Why then the unaligned 
widgets, a hallmark of pack-based layouts? 


This turned out to be a result of using many nested frames. For example the buttons were placed 
into their own frame, and then that placed into the rest of the window. Because of that, the 
individual buttons couldn't be aligned with widgets in the rest of the user interface. 


Nested frames were required when using pack, but often with grid it is better to avoid them except 
in exceptional circumstances. That allows you to make different parts of the user interface line up 
(at the expense of dealing with a lot of columnspan/rowspan tweaking). 


A more substantial reorganization would have likely removed the nested frames, but particularly 
with adjusting the buttons, this relatively simple layout could be made to work with just a few 
tweaks. 


You'll notice a lot of older Tkinter user interfaces have the problem here of their contents running to 
the edge of the windows, which often doesn't look right. I've gotten into the habit of placing a 
ttk.Frame directly inside each toplevel, with some additional padding, and then placing the rest 
of the user interface inside that. 
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Like Preferences, the Find dialogs were also modal, which meant you had to dismiss them before 
doing any editing of your file, though at least they did remember the previous settings when you 
reopened them. These were eventually changed to be regular modeless windows. 


About Dialog 


Speaking of modal dialogs, the About box was also originally modal. Not only that, getting more 
information (e.g. the IDLE README file), resulted in launching another modal dialog, which 
needed to be dismissed to go back to the first modal dialog, which needed... etc. 
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IDLE 


Python's Integrated DeveLopment Environment 


email: idle-dev@python.org 
https://docs.python.org/3.4/library/idle.html 


Python version: 3.4.3 Tk version: 8.5.18 


IDLE version: 3.4.3 


000 About - Readme 
IDLE is Python's Tkinter-based Integrated Development Environment. 


IDLE emphasizes a lightweight, clean design with a simple user interface. 
Although it is suitable for beginners, even advanced users will find that 
IDLE has everything they really need to develop pure Python code. 


IDLE features a multi-window text editor with multiple undo, Python colorizing, 
and many other capabilities, e.g. smart indent, call tips, and autocompletion. 


The editor has comprehensive search functions, including searching through 
multiple files. Class browsers and path browsers provide fast access to 

code objects from a top level viewpoint without dealing with code folding. 
There is a Python Shell window which features colorizing and command recall. 
IDLE executes Python code in a separate process, which is restarted for each 
Run CFS) initiated from an editor window. The environment can also be 
restarted from the Shell window without restarting IDLE. 

This enhancement has often been requested, and is now finally available. The 
magic "reload/import *" incantations are no longer required when editing and 


testing a module two or three steps down the import chain. 


eran Firewall software may warn about the connection IDLE makes to its 


O nr neinn bhie ammm de ¿mbaama? Teanwkanele i nbanlanrna This rammnrilimm 


Close 


IDLE's doubly-modal About dialog (Mac OS X) 


Making the dialog non-modal was the first priority. Second, the nested dialogs were eliminated, 
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using a progressive disclosure technique. The dialog when launched is fairly sparse, but contains a 
'More...' "link", which when clicked expands the window to show one of the documentation files, 
with an option to switch to any of the others. 


The 'More...' "link" is effectively playing the role of a button, but taking advantage of everyone's 
familiarity with web browsers to provide a visually simpler alternative. As far as implementation, 
we use a (classic, non-themed) label widget, colored blue, and attach a mouse click binding to it. 


One thing you can do to help convey that the link is clickable is change the cursor when the mouse 
is over it (via the "cursor" option found on many widgets). On OS X, choose the platform-specific 
"pointinghand" cursor, on Windows and Linux choose the "hand2" cursor, which actually gets 
mapped to something more appropriate on those platforms. 
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About IDLE 


IDLE Readme 
IDLE is Python's Tkinter-based Integrated Development Environment. 
IDLE emphasizes a lightweight, clean design with a simple user interface. 


Although it is suitable for beginners, even advanced users will find that 
IDLE has everything they really need to develop pure Python code. 


IDLE features a multi-window text editor with multiple undo, Python colorizing, 
and many other capabilities, e.g. smart indent, call tips, and autocompletion. 


The editor has comprehensive search functions, including searching through 
multiple files. Class browsers and path browsers provide fast access to 
code objects from a top level viewpoint without dealing with code folding. 


There is a Python Shell window which features colorizing and command recall. 


Revised About Box (Mac OS X) 


Online Help 


IDLE also had a (needless to say, modal) help dialog which displayed information on using the 
program. This displayed a plain text help file that looked similar to the 'About - Readme’ window 
above. 


At the same time, like the rest of Python, there was reference documentation, created as 
"restructured text" which can then be formatted using a tool called Sphinx into HTML, text, etc. 


The documentation in IDLE's help dialog was based on a separate, but similar plain text file. 
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Keeping the two in sync was a problem. They were separate because Sphinx's plain text rendering 
didn't look all that good, and all the extra navigation etc. in the HTML rendering wouldn't be 
needed for online help, and then there's the hassle of opening a web browser, etc. [Issue#16893] 


Tk's text widget is smart enough to handle the very basic formatting used in IDLE's documentation, 
and Python includes an HTML parser in its standard library. Putting the two together made 
displaying a simplified version of the HTML reference documentation easy. 


0090 IDLE Help 
Toc |) IDLE 
IDLE is the Python IDE built with the tkinter GUI toolkit. 


IDLE has the following features: 


* coded in 100% pure Python, using the tkinter GUI toolkit 

* cross-platform: works mostly the same on Windows, Unix, and Mac OS X 

* Python shell window (interactive interpreter) with colorizing of code input, output, and error 
messages 

* multi-window text editor with multiple undo, Python colorizing, smart indent, call tips, auto 
completion, and other features 

* search within any window, replace within editor windows, and search through multiple files 
(grep) 

* debugger with persistent breakpoints, stepping, and viewing of global and local namespaces 
* configuration, browsers, and other dialogs 


1. Menus 


IDLE has two main window types, the Shell window and the Editor window. It is possible to have 
multiple editor windows simultaneously. Output windows, such as used for Edit / Find in Files, are a 
subtvne of edit window. Thev currentiv have the same tan menu as Editor windows hut a different 


Online Help using text widget (Mac OS X) 


It's easy to get carried away here. Back in the mid-1990's, a tiny HTML parser in Tcl spawned a 
slew of "web browser in a text widget" adventures, first in Tcl and then in other languages, e.g. 
Python's Grail. Trying to keep up with everything that large teams of developers are putting into 
real web browsers is a fool's errand. Yet, for very limited and constrained subsets of HTML as 
might be found in online help, it's an entirely reasonable approach. 


Query Dialogs 

Still with the modal dialog theme, IDLE used the "simpledialog" package which is distributed as 
part of Tkinter to request certain small pieces of information from the user via modal dialogs. An 
example is the "Goto line..." command. This, along with an example of the alert that is presented if 
you type in something invalid is shown below. 
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000 Goto 0 0 Goto 


Go to line number: Not an integer. 


foo| Please try again 


GOED Cancel 
—— ama 


Goto line dialog and error handling (Mac OS X) 


The alert-on-dialog isn't quite as bad as the dialog-on-dialog pattern we saw before. But these 
dialogs could certainly stand to be cosmetically updated, and a few other tweaks made. For 
example, while they correctly interpreted hitting the Return or Escape keys as synonymous with 
pressing OK or Cancel, they didn't also allow for the alternate Mac conventions (Enter key on 
numeric keypad and Command-period) [Issue#24812]. There were some other customizations that 
would have been nice to have, e.g. changing the name of the OK button, that simpledialog didn't 
support. 


Regarding the error handling, things were in some cases handled worse. For example, there is a 
command to open an editor window containing the source of a module from Python's stdlib. See 
what happens if you make a typo. 


000 Module 


Enter the name of a Python module 
to search on sys.path and open: 


| 
OK Cancel 


Python 3.4. i 
[GCC 4.2.1 A module not found 


Type "copyr 


Open module dialog with error (Mac OS X) 


Because the dialog doesn't know if the module name is correct, validation isn't done until after the 
dialog is dismissed. So the error alert gets attached to another window, and to try again you have to 
dismiss that and go to the menu to reopen the dialog, and try again (from scratch). 


There were a couple of places in the code where more validation in the dialog was really necessary. 


138 


Because the "simpledialog" code was part of Tkinter, and wasn't readily extensible in the ways 
needed, developers had to resort to "inheritance by text editor" (i.e. copy the entire simpledialog 
code and modify the copy). Twice, separately. 


Since the appearance needed to be updated anyway, we generalized things, and ignored what was in 
Tkinter's simpledialog module altogether. Instead, a single general-purpose replacement was created 
that could be used throughout IDLE (and still resulted in less code). 


Goto 


Go to line number: 


fool | 


Must be an integer 


New query dialog (Mac OS X) 


Besides the updated widgets and alignment, notice how error messages from invalid input are now 
shown in the dialog itself (a technique seen frequently in web applications), rather than a separate 
alert. For OS X, we also made sure to add key bindings for the numeric keypad Enter key and 
Command-period, and also made sure the window looked like a modal dialog is supposed to via this 
little gem: 


self.tk.call('::tk::unsupported::MacWindowStyle', 'style', self. _w, 
'moveableModal', '') 


As far as validation, the query dialog was structured to accept a validation callback, which could 
then handle arbitrary criteria. For example, here is the validation code used when people enter the 
name of a new theme, to make sure it fits certain syntactical requirements, and also hasn't been 
already used. 


def newtheme(self): 
def validate_theme(s): 
if not s: 
raise ValueError('Cannot be blank') 
if len(s) > 30: 
raise ValueError('Cannot be longer than 30 characters') 
if s in self .all_theme_names(): 
raise ValueError('Name already used') 
new_theme = querydialog. a ay self, prompt='...' 
title='Create New Theme', validatecmd=validate _theme) 
if new_theme is not None: 


A generic 'integer' validation callback, with an optional minimum and maximum, was added as part 
of the query dialog module to be used for dialogs like the 'Goto line...’ dialog. 


Dialog Placement 


A number of dialogs, including alerts, file save, etc. were appearing in the middle of the screen, 
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rather than close to the window that they were associated with. [Issue#25173] 


Choosing the right window as the parent of the dialog is important, because it ensures the dialog 
window appears near that window. On Mac OS X, these dialogs are often attached to the title bar of 
the parent window (see the error alerts in the previous section). 


The front ends to these dialogs in Tkinter support both a master and a parent. While most of 
the time, "master" and "parent" are used interchangeably in Tkinter, that's not the case here. If you 
provide only the master, the dialog won't be attached to that window (but the dialog still needs an 
existing window to create the dialog, which is why the master parameter is there). If the dialog is 
associated with another window, be sure to use the parent parameter. 


Window Integration 


Multiple people had hoped to make it possible to have everything displayed in a single window, to 
avoid the window management hassles that can sometimes trip up people, e.g. [Issue#9262], 
[Issue#24826], [Issue#24818]. 


Below is an early, partially functional, mockup of some of the things we wanted to be able to 
accomplish. 
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@ © @ uipreferences.py - /Users/roseman/vboxshare/cpython/Lib/idlelib/uipreferences.py (3.6.0a0) 
uipreferences.py uitabs.py querydialog.py + 


""""When a theme, color or the active element changes, update the 
colors in the UI, both the sample and also the color wells, to match 
the new state.""" 
theme = self.theme_v.get() 
for element in self.elements: 
elt = self.elements[element] [9] 
fg = self .current_color(self.theme_v.get(), element, 'fg') 
bg = self.current_color(self.theme_v.get(), element, ‘bg') 
if elt == 'cursor': 
bg = idleConf.GetHighlight(theme, ‘normal', fgBg='bg') 
self.sample.tag_config(elt, background=bg, foreground=fg) 
if element == self .element_v.get(): 
self .foregroundWell.configure(background=fg) 


o que acre) 


def all_theme_names(self): 
themelist = self.default_themes[: ] 
userlist = idleConf.GetSectionList('user', 'hiahliaht')> 


Program stopped by exception. 


yr & F G&G E 
Go Step Over Out Stop 


bg '#ffffff' 
element ‘Shell Normal Text' 


init self.rebuild_themes_list() , i 
rebuild_themes_list self.theme_changed() elt a . 
theme_changed() self.update_colors() fg #770000 
update_colors() x=5/0 self <__main__.ThemesPane 
ZeroDivisionError: division by zero theme ‘IDLE Classic’ 


hh Aik i. 


Type "copyright", "credits" or "license()” for more information. 
>>> 

[DEBUG ON] 

>>> 


===== RUN /Users/roseman/vboxshare/cpython/Lib/idlelib/uipreferences.py ===== 


Ln: 478 — Col: 8 


Early mockup of window integration (Mac OS X) 


At this point, almost everything here has been completed, and it ended up looking almost identical 
to the original mockup. See, once in a while it happens! 


Tabbed Editor 


Even beginner programmers have to juggle multiple different source files. If each gets its own 
window, as was the case originally in IDLE, things can get messy and/or lost pretty quickly. Using 
tabs to organize multiple files in a single window is a familiar, effective solution. 


When architecting your application, don't build large components as subclasses of Toplevel, or 
assume they'll be the only thing in the window in the future. Getting around that assumption in the 
code took a large amount of work. If components are instead built as frames, they can be more 
easily inserted into a toplevel, a paned window, a tabbed notebook, another frame, etc. 
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Luckily, we can rely on the ttk. Notebook widget to provide the tabbed user inteface, just like we did 
in Preferences. 


Or maybe not. 


Unfortunately, the ttk. Notebook widget (and the underlying platform widgets it uses) only really 
support displaying and switching between a small, fixed number of tabs. There's nothing built-in to 
support adding or closing tabs from the user interface, which we definitely need here. And as every 
programmer knows, it is more than possible to need a large number of tabs. 


As you've seen in different editors and word processors, everyone does things slightly differently. 
We did our own custom tab widget (sigh...) for IDLE. The design borrowed heavily from the 
TextMate editor on the Mac. It allows creating new tabs, closing old ones, dragging to rearrange the 
order, tooltips on each tab, indicating if the contained file needed saving, etc. When the number of 
tabs grows too large to comfortably display, the remainder are accessible via a popup menu on the 
last visible tab. 


The tabbed widget implementation relies on a single Tkinter canvas to display the row of tabs and 
handle all interaction. The actual switching of window content is handled completely outside of the 
widget, with a simple callback mechanism used to coordinate everything. 


Debugger 


The design of the original debugger, along with having it's own set of flaws [Issue#17942], was too 
tall to be integrated like we wanted to do. 
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¿000 Debug Control | 


= 
Stack | | Source 

Go Step Over Out Quit — 
op r = Locals | | Globals 


Untitled.py:1: <module>() 


'bdb'.run(), line 431: exec(cmd, globals, locals) 
'_main__'.<module>(), line 1: import random 


Locals 


—builtins_. <module 'builtins' (built-in)> 


_doc__ None 

file '/Users/roseman/desktop/Untitlec 
—loader_ <class '_frozen_importlib.Builtinin 
__name__ ' _main_' 

—package_ None 

_Spec__ None 


Original IDLE Debugger (Mac OS X) 


The user interface was substantially revised, with a layout that would work both in a standalone 
window, and when integrated. The new version uses a paned window to separate the controls and 
stack on the left from the variable display on the right. Both the stack and variable display are 
implemented using tree view widgets. This also provides a great deal of control when it comes to 
how much space each element will use. 


000 Debug Control 
r& GF Gm ® 
Go Step Over Out Stop Options Y Locals 
Untitled.py:1: <module>() __builtins__ <module 'builtins' (built- 
_doc__ None 
dos exec(cmd, globals, local file '/Users/roseman/deskto 
> ie __loader__ <class '_frozen_importlil 
__name__ '_main_' 
_ package. None 
_spec__ None 


. mi 4 


leet 
New IDLE Debugger (Mac OS X) 
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Integrated Shell and Debugger 


To achieve the integration of the shell and the debugger with the tabbed editor, another paned 
window was used. Additional controls will be added to show/hide the panes as the implementation 
progresses. 


The embedded shell is interesting too. Recall that IDLE normally has a single Python shell window 
running another Python process; when modules in an editor are "run" they do so via that shell. It's 
nice to have that big shell available, and we don't necessarily want to start up a separate shell in the 
editor. 


New in Tk 8.5, the Text widget actually supports the ability to create "peers", which are separate 
widgets, but they share the same text backend. That means when something changes in one, it 
changes in the other. It's a seamless way to solve our problem here. 


Workarounds, Hacks, and More 


This being a chapter on actual experiences modernizing a real application, it would be a lie to say 
that the underlying user interface toolkit (Tk and the Tkinter wrapper) always worked exactly as it 
should. Like IDLE, Tkinter and Tcl/Tk are the results of incredible volunteer efforts. That being 
said... 


Tk and Tkinter have some bugs and rough edges. I know, you're shocked. 


In this section, I'll try to catalog just a few of the particular "gotchas" that we ran into, as well as 
provide some little tips that don't necessarily fit elsewhere, but help provide a bit more polish to the 
user interface. 


Tool Tips 


e tool tips broken on mac [Issue#24570] 
e MacWindowStyle help for tooltips, vs. wm overrideredirect elsewhere 


Context Menus 


e bogus text widget bindings interfere with popup clicks [Issue#24801] 
e two different popup click bindings needed on Mac [Issue#24801] 


Peer Text Widgets 
+ broken peer text widget API in Tkinter [Issue#17945] 


Modal Windows 
e mac not doing fully modal, plus window style [Issue#24760 | 
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